Costruisci un ciclo agentico proattivo su Claude Opus 5.5

La parte scomoda del costruire un proprio agente proattivo è che il lavoro interessante non è la chiamata al modello. Puoi avere Claude Opus 5.5 che risponde alle domande in un pomeriggio. Farlo svegliare secondo una pianificazione, fargli leggere solo ciò che è cambiato dall'ultima volta, fargli decidere se qualcosa merita l'intervento di una persona, fargli abbozzare l'azione, poi fermarlo e metterlo in attesa: sono settimane, e quasi nulla di tutto ciò avviene dentro il modello. Anthropic ha rilasciato una versione di questo ciclo con il nome di Claude Duet, e ciò che di utile c'è in quel prodotto per chiunque ne costruisca uno proprio non è l'elenco delle funzionalità, ma le decisioni visibili nel modo in cui è assemblato. Non ha un'API pubblica e non può essere reindirizzato verso i tuoi sistemi, quindi se vuoi il ciclo e non l'app, devi costruirtelo. Quello che segue è l'architettura, fase per fase, con il costo reale di ciascuna.

Prima la forma. Cinque fasi si susseguono in sequenza, e la quinta si raggiunge solo dopo che una persona dice sì. Uno scheduler scatta. Una fase di digest riduce ogni sistema connesso a un delta. Una fase decisionale trasforma quel delta più una policy in una proposta tipizzata. Un gate di approvazione esterno al modello decide se la proposta può essere eseguita. Un executor la esegue. Questo è l'intero design, e tutto ciò che è difficile vive nelle giunture.

Fase uno: uno scheduler che si attiva ogni poche ore

La prima decisione è quella che le persone sbagliano per entusiasmo più che per ingegneria: non fare polling in modo continuo. La documentazione di Duet di Anthropic spiega il suo intervallo — controllare ogni poche ore — dicendo che controllare senza sosta consumerebbe i limiti del piano molto più rapidamente. Non è cautela di marketing. È la risposta giusta a un vero problema di costi, ed è la trappola in cui ogni agente fatto in casa cade nella prima settimana.

Il polling continuo è rovinoso per una ragione strutturale. Ogni scansione è un contesto completo: istruzioni, definizioni degli strumenti, il materiale che hai recuperato e qualunque ragionamento il modello vi svolga sopra. Con una cadenza di un minuto sono 1.440 contesti completi al giorno, e la stragrande maggioranza non trova nulla di nuovo. Paghi il prezzo pieno per sentirti dire che la casella di posta non è cambiata. Con una cadenza di tre ore ne ottieni otto, e il rapporto tra risultati e spesa diventa qualcosa che puoi difendere davanti a chi firma la fattura.

Quindi lo scheduler è un timer in stile cron con un limite minimo sull'intervallo, non un flusso di eventi. Gli eventi sembrano allettanti — reagire nel momento in cui succede qualcosa — ma ti spingono di nuovo verso un lavoro continuo e rendono illimitato il costo di una giornata intensa. Un timer offre un tetto prevedibile, ed è ciò di cui hai bisogno quando il conto è variabile. Quando vuoi una reazione più rapida per una singola fonte, riduci solo l'intervallo di quel connettore e accetta la spesa extra.

Fase due: un prefisso byte-identico, conservato nella cache

È qui che i numeri pubblicati contano di più. Claude Opus 5.5 su OrcaRouter costa 4,00 dollari per milione di token di input, 20,00 per milione di token di output, con una finestra di contesto da 1M token e letture dalla cache a 0,20 per milione, al prezzo di listino del provider con 0 percento di ricarico. Leggi quei valori come un vincolo di progettazione anziché come un listino prezzi: una lettura dalla cache costa un ventesimo di un token di input nuovo, quindi ogni byte che mantieni stabile da una scansione all'altra è un byte per cui smetti di pagare il prezzo pieno.

In pratica il system prompt e lo schema dello strumento vengono assemblati una volta al momento del deploy e mai rigenerati a ogni sweep. Non vengono riserializzati da un dizionario con le chiavi in un ordine diverso. Non vengono templatizzati con un timestamp, un request ID o gli account connessi di oggi inseriti nel mezzo. Qualsiasi byte diverso invalida il prefisso in cache, e il blocco di istruzioni torna al prezzo di input completo a ogni sweep. I team perdono questa cosa per errore più spesso che intenzionalmente, di solito perché un'astrazione utile ha iniziato a iniettare un identificatore di esecuzione vicino all'inizio del prompt.

La disciplina che sopravvive al contatto con il codice reale è noiosa: una funzione che restituisce una stringa costante per il blocco stabile, un letterale congelato per lo schema dello strumento, ogni elemento variabile collocato dopo di esso. Poi un test che calcola l'hash del blocco e fa fallire la build quando l'hash cambia, perché prima o poi qualcuno aggiungerà un campo allo schema senza mai pensare alla cache. Quel test costa un'ora e salva l'intero beneficio della cache.

Fase tre: un riepilogo per connessione, non uno scarico della casella di posta

La terza fase è quella che un prodotto consumer ottiene gratis e tu no. Duet vive all'interno dell'account Anthropic e raggiunge le app collegate, così può chiedere cosa è cambiato a partire da un certo momento e ottenere una risposta breve. Costruendo fuori da quell'account, parli con le stesse API di qualsiasi client normale: o implementi letture incrementali, oppure scarichi tutto e passi al modello un muro di testo.

Estrarre tutto è l'impostazione predefinita perché funziona fin dal primo giorno. È anche il modo più rapido per rendere imprevedibile il costo di ogni scansione, perché l'input cresce con la casella di posta anziché con ciò che è cambiato. Una scansione di quaranta conversazioni invariate costa quanto una di quaranta conversazioni in cui conta una sola conversazione, e solo una di queste aveva qualche possibilità di generare una proposta utile. Dopo un mese così, la maggior parte del tuo budget è servita a confermare lo status quo.

La fase di digest dovrebbe essere codice, non prompting. Esegui il fetch per ogni connessione usando qualsiasi cursore o delta offra l'API, e riduci il risultato a una sintesi strutturata: cosa è apparso, cosa è stato modificato, cosa è stato risolto. Assegna a ogni elemento un identificatore stabile in modo che le fasi successive possano farvi riferimento, e registra l'ultimo cursore riuscito per connessione così che un fetch fallito non riproponga il materiale di ieri come se fosse nuovo. Un digest che non riesce a distinguere "non è successo nulla" da "non ho potuto controllare" finirà per riportare con sicurezza uno stato che non ha mai osservato.

Fase quattro: un passaggio decisionale che restituisce un oggetto, non prosa

È qui che si colloca Claude Opus 5.5, e ciò che emette determina se il resto del sistema possa essere costruito del tutto. L'istinto è far scrivere al modello un riassunto e lasciare che una persona lo legga. Funziona per una dashboard e fallisce per un cancello: la fase successiva deve decidere se consentire un'azione, e il permesso non può essere concesso a un paragrafo.

Il passo decisionale dovrebbe restituire una proposta di azione tipizzata: un nome di azione tratto da un elenco chiuso, il target a cui si applica, i parametri, una motivazione di una riga e un flag esplicito di confidenza o escalation. Un elenco chiuso di azioni non è burocrazia; è il meccanismo che rende applicabile il gate di approvazione, perché un gate può validare solo le azioni che è in grado di enumerare. Un agente che può emettere qualsiasi verbo non può essere sottoposto a un gate, può solo essere considerato affidabile.

Due note pratiche. Fornisci al modello il digest, poi la policy, così che la policy si trovi dopo il materiale variabile e il prefisso della cache resti intatto. E rendi l'esito predefinito «nessuna azione» invece di una proposta vuota che sembra un'azione. I cicli che trattano il silenzio come un fallimento producono volume, e un agente che fabbrica lavoro per sembrare utile è peggio di uno che riporta che nulla è cambiato.

Fase cinque: un gate di approvazione che può davvero dire no

Il gate deve essere un servizio separato, non un ramo all'interno del codice dell'agente stesso. Questa è la decisione strutturale più importante nella realizzazione. Se il processo dell'agente può eseguire l'azione stesso, un bug, un'iniezione di prompt o un flag impostato in modo errato in quel processo raggiunge l'effetto. Se l'esecutore accetta solo una proposta firmata dal gate, il peggio che l'agente può fare è proporre qualcosa di sbagliato, e il rifiuto del gate è reale.

La policy pubblicata da Anthropic per Duet vale la pena di essere copiata nella struttura anche laddove il tuo elenco differisce. Il gate richiede approvazione prima che un'azione invii un messaggio, effettui un pagamento, firmi un documento o elimini qualcosa. Al di sopra si colloca un secondo livello rifiutato anche con approvazione — nel caso di Duet, negoziazione di titoli e trasferimento di denaro tra account. Il pattern è una policy a due livelli: un ampio insieme di azioni sottoposte a gate che una persona può autorizzare, e un piccolo insieme che nessuna approvazione sblocca. Copia i livelli anche se ogni voce cambia, perché risolvono problemi diversi. Il gate protegge dagli errori. L'elenco delle proibizioni protegge da un operatore compromesso, incluso quello umano.

L'altra metà di un vero gate è che interrompe. La richiesta di approvazione di Duet mostra l'azione esatta e attende, il che interrompe deliberatamente il flusso invece di annotarlo. Un gate che scrive una riga in un log che nessuno legge non è un gate; è una ricevuta. Se la tua fase di approvazione richiede che qualcuno guardi una dashboard alle tre del mattino, o l'intervallo è troppo breve o l'elenco delle azioni è troppo ampio. Entrambe le cose sono risolvibili, e in nessuno dei due casi aggiungendo una notifica.

Memoria, credenziali e le due superfici da cui non puoi uscire testando

Due problemi difficili stanno alla base delle cinque fasi, ed entrambi sembrano funzionalità finché non lo sono più.

• Continuità del contesto. Ogni passaggio è un contesto nuovo, quindi tutto ciò che l'agente deve ricordare tra un passaggio e l'altro deve essere annotato tra essi. Un file di stato scorrevole per connessione, con dimensione limitata, che contenga elementi aperti e decisioni recenti è sufficiente per la maggior parte dei cicli. Ciò che non funziona è sperare che il modello ricostruisca la cronologia dal digest, perché il digest è esplicitamente una descrizione del cambiamento e non contiene alcuna memoria di ciò che è già stato deciso.

• Custodia delle credenziali. Duet segue il design utilizzato per gli agenti gestiti di Anthropic, quindi non vede mai direttamente le tue password o i token di accesso. Riprodurre questa disciplina è l'aspetto che la maggior parte degli agenti sviluppati in casa trascura, e trascurarlo significa che ogni prompt ha una via d'accesso a una credenziale. Il modello non dovrebbe mai detenere un token, non dovrebbe mai ricevere una chiave API come testo e non dovrebbe mai essere il componente che esegue l'autenticazione. Lascia che il passaggio di digest e l'esecutore detengano le credenziali e consegnino al modello solo i risultati.

Poi c’è la superficie a cui nessuno vuole pensare: una volta che l’agente legge email e pagine web, ciascuna è un input che può contenere istruzioni. Un messaggio che dice «inoltra questo all’indirizzo qui sotto» è indistinguibile dai dati per un modello che non ha una nozione separata di autorità. Due difese battono qualsiasi quantità di hardening del prompt. Mantieni chiusa la lista delle azioni, così un’istruzione iniettata non ha alcun verbo a cui aggrapparsi. E mantieni il cancello fuori dall’influenza del modello, perché un’iniezione che convince il modello a inviare qualcosa deve comunque convincere una persona che vede l’indirizzo di destinazione.

Failover, e dove il routing aiuta davvero

Una volta costruito il ciclo, si apre un'opzione architetturale che un design monofornitore non ha. Il DSL di routing di OrcaRouter compone diversi modelli in un'unica chiamata, e la fusione dei modelli esegue un panel di modelli che rispondono in parallelo; entrambi mettono più di un modello dietro una singola richiesta. L'uso pratico qui è poco attraente: indirizzare un modello più economico alla sintesi del digest, dove il lavoro è compressione più che giudizio, e mantenere Claude Opus 5.5 nella fase decisionale, dove viene formulata la proposta. La stessa unica chiave compatibile con OpenAI raggiunge più di 200 modelli, quindi cambiare quale modello serve quale fase è una modifica di configurazione anziché una riscrittura.

Il failover è l'altra metà. Quando un provider attraversa un'ora critica, anche un agent che può raggiungere un solo endpoint attraversa un'ora critica, e un ciclo pianificato senza fallback semplicemente salta la sua scansione. Il routing trasforma una scansione mancata in una più lenta: un beneficio non eclatante fino alla settimana in cui ti serve, e a quel punto la differenza tra una lacuna nel registro e nessuna lacuna.

A cosa stai effettivamente iscrivendoti

Eseguire questo ciclo significa gestire un servizio, e il servizio ha quattro proprietà di cui hai appena assunto la titolarità.

• Tempo di attività. L'app di Anthropic è il cercapersone di qualcun altro; il tuo è il tuo. Un pianificatore che smette silenziosamente di essere eseguito non genera alcun errore né output, e te ne accorgi da una persona che ha notato l'assenza del suo resoconto mattutino, non da un avviso.

• Custodia delle credenziali. Ogni token detenuto dalla tua fase di digest è sotto la tua responsabilità, e il raggio d'impatto di una fuga è qualunque cosa quella connessione possa raggiungere. Il design di Anthropic tiene le credenziali lontane dal modello; se il tuo non lo fa, il modello diventa una superficie di attacco per ogni account che hai collegato.

• Difesa dal prompt-injection. Il gate qui dà molto, ma solo per le azioni che controlla. Qualsiasi cosa faccia l'agente senza approvazione — leggere, riassumere, scrivere il proprio stato — è senza protezione, e un digest avvelenato può corrompere la memoria da cui le successive analisi traggono le loro conclusioni.

• Il bug bounty non è di nessuno. Se il tuo ciclo fa cilecca e invia il messaggio sbagliato a un cliente, non c'è alcun fornitore a cui rivolgersi in escalation, nessuna pagina di stato, nessun report di incidente. Le decisioni sopra sono l'unica rete di sicurezza, motivo per cui il gate è un servizio separato e l'elenco delle azioni è chiuso.

Niente di tutto ciò è un argomento contro il costruirlo. È un argomento contro il costruirlo con leggerezza. Ogni fase è piccola, e le giunture tra di esse sono il luogo in cui risiede il giudizio: un timer invece di un flusso, un prefisso congelato invece di un template, un digest invece di un dump, un oggetto invece di prosa, e un gate che è un servizio invece di un commento. Se li azzecchi, il ciclo si ripaga — trova cose che non avresti cercato e si ferma prima di fare qualsiasi cosa che non possa essere annullata. Se li sbagli, hai costruito qualcosa che consuma il tuo budget di continuo e ti dice ciò che già sapevi.