Agenti AI sotto review: configurare Claude Managed Agents con ant apply

Dal 3 settembre 2026, gli agenti AI di Claude Managed Agents hanno un flusso operativo più concreto: ant apply trasforma i file del repository in agenti, ambienti, skill, memory store e deployment attivi. Il vero salto è un altro: la configurazione degli agenti può essere sottoposta alla stessa review del codice prima di arrivare in produzione.

La configurazione degli agenti AI diventa stato revisionabile

Claude Managed Agents è il sistema di agenti in hosting di Anthropic, pensato per attività asincrone e di lunga durata. Un agente definisce modello, prompt, tool e skill; un ambiente stabilisce dove viene eseguito; un deployment può avviarlo secondo una pianificazione.

Non va confuso con un subagent di Claude Code salvato in .claude/agents/. Questa novità riguarda le risorse del servizio di agenti gestiti disponibile tramite la Claude API.

Quando un team crea queste risorse dalla Console o con chiamate API isolate, lo stato utile finisce in due posti. Il servizio remoto conserva la risorsa effettiva; uno script, un documento o la memoria di un collega spiegano invece come ci si è arrivati. A ogni passaggio di consegne occorre ricomporre i due pezzi.

Con ant apply, questo compito passa al repository. Le risorse si descrivono in Markdown, YAML o JSON. La CLI confronta i file con le risorse remote, mostra un piano, chiede l'approvazione e infine applica la modifica.

Prompt di sistema, accesso ai tool, ambiente, pacchetto di skill, memory store e pianificazione entrano così in una pull request. Chi fa la review può vedere cosa cambierà prima che una persona, o un job CI dotato delle credenziali di deployment, intervenga in produzione.

Questo articolo descrive un workflow per i team che stanno già valutando Managed Agents. Se si usa soltanto l'app Claude, Claude Code o un loop proprietario basato sulla Messages API, ant apply non modifica l'assetto esistente.

Il lockfile rende affidabile il passaggio di consegne

Il file decisivo non è solo la definizione dell'agente. È claude-lock.json.

La prima applicazione riuscita crea il lockfile nella directory da cui viene eseguito il comando. Conviene lanciare il comando dalla radice del repository e versionare il lockfile insieme ai file delle risorse.

Il lockfile registra l'origine dell'API, l'organizzazione, il workspace e l'ID remoto generato per ogni file locale. Conserva inoltre un hash locale e uno remoto. Il primo rileva le modifiche al file; il secondo segnala che qualcuno ha cambiato la risorsa dalla Console o tramite un altro percorso API.

È, in pratica, una rubrica unita a una ricevuta. Il file della risorsa descrive il risultato desiderato; il lockfile indica quale oggetto attivo appartiene a quel file e com'era ciascun lato dopo l'ultima applicazione.

È questo meccanismo a rendere più lineare il passaggio di consegne. L'operatore successivo, o il runner CI, non deve indovinare quale ID agente corrisponda a agents/reviewer.md: legge la mappatura e aggiorna la stessa risorsa invece di crearne una copia.

Quando l'API richiederebbe normalmente un ID, le risorse possono richiamarsi tra loro tramite percorsi relativi. Apply calcola l'ordine delle dipendenze, crea o aggiorna ogni risorsa e inserisce gli ID reali. Un agente può puntare alla directory di una skill; un deployment può fare riferimento al proprio agente, ambiente e memory store.

I riferimenti ad agenti e skill vengono fissati alla versione applicata in quella esecuzione. Se una skill arriva da un URL GitHub, resta ancorata al commit risolto finché non si usa --upgrade. La review ha quindi un obiettivo preciso, non ciò che per caso si trova in fondo a un branch in movimento.

Il vero conto economico è il lavoro di handover

ant apply non azzera il costo del lavoro sugli agenti. Sposta la voce di budget.

Prima si pagavano configurazioni ripetute, verifiche e passaggi di consegne. Ora si pagano l'impostazione del repository, la review delle pull request, la responsabilità della CI e la manutenzione del lockfile. La convenienza dipende dalla frequenza delle modifiche e dal numero di ambienti in cui vanno replicate.

Quello che segue è un esempio dichiarato, non un benchmark né una promessa di risparmio da parte di Anthropic.

Supponiamo che un team apporti quattro modifiche di configurazione al mese in tre ambienti di destinazione. Ogni passaggio manuale richiede 15 minuti per ciascuna modifica e per ciascun ambiente.

Il lavoro manuale mensile è:

4 changes × 3 environments × 15 minutes = 180 minutes

Supponiamo ora che il percorso basato sul repository richieda 30 minuti di review per ogni modifica, più 10 minuti per applicarla e verificarla in ciascun ambiente.

Il lavoro mensile via repository è:

4 changes × (30 review minutes + 3 × 10 apply minutes) = 240 minutes

Con questi dati, il workflow nel repository richiede 60 minuti in più ogni mese. È la risposta che serve quando il passaggio manuale è già economico.

Il punto di pareggio è di 20 minuti per ogni passaggio manuale, prima di conteggiare configurazione e manutenzione. Se il passaggio misurato richiede 30 minuti, lo stesso percorso manuale sale a 360 minuti, mentre quello nel repository resta a 240 minuti. La differenza è di 120 minuti, ma rimane soltanto il risultato di un foglio di calcolo finché il team non misura il lavoro reale.

Affiancate a quei minuti il costo orario complessivo del personale. Aggiungete poi l'impostazione iniziale e i costi ricorrenti per esaminare i piani non riusciti, risolvere il drift e mantenere la CI. Il tool merita un posto nel processo quando questo conto completo batte il metodo attuale, non quando la demo appare ordinata.

Chi trae vantaggio da questo workflow

Un team di piattaforma ottiene un solo punto di review

Il responsabile di piattaforma di un'azienda software può riunire in una sola pull request un agente, le sue skill, l'ambiente, il memory store e il deployment pianificato. I reviewer esaminano l'intera modifica operativa nello stesso punto, senza confrontare un file di prompt con screenshot presi da una console remota.

Il vantaggio è la tracciabilità. Da una modifica unita al branch si può risalire al piano delle risorse e allo stato del lockfile che ne è derivato.

Un'agenzia semplifica il passaggio al cliente

Il responsabile tecnico di un'agenzia può conservare i file di ogni cliente insieme al lockfile della relativa organizzazione e del relativo workspace. Quando subentra un altro operatore, la mappatura viaggia con il repository.

Il vantaggio è ridurre i dubbi sull'identità delle risorse durante il passaggio. Questo non rende un lockfile trasferibile tra clienti: Apply rifiuta credenziali associate a un'organizzazione o a un workspace diversi, proprio il confine che un'agenzia dovrebbe preservare.

Un team operativo ottiene uno step di deployment esplicito

Un responsabile operativo può visualizzare l'anteprima di una modifica nella pull request e applicare la directory confluita nel branch predefinito con ant apply --yes .. Il punto finale conta: un apply senza argomento riconcilia soltanto le risorse già tracciate nel lockfile e può ignorare un nuovo file.

Il vantaggio è uno step di deployment ripetibile. In esecuzione serve comunque un unico responsabile, perché Apply non blocca il lockfile: due job simultanei possono entrare in conflitto sullo stesso stato.

Un responsabile della sicurezza può fermare il drift

Il responsabile della sicurezza può usare l'hash remoto per far emergere una modifica dalla Console prima che lo stato del repository la sovrascriva. Apply si blocca se una risorsa gestita è stata modificata, archiviata o eliminata al di fuori dei file.

Il vantaggio è una decisione esplicita: si esamina e riconcilia la modifica remota, oppure si usa --force per sovrascriverla consapevolmente. I team che richiedono Zero Data Retention o la copertura di un HIPAA Business Associate Agreement devono invece rinviare l'adozione di Managed Agents, perché al momento il servizio non è idoneo a nessuno dei due requisiti.

Un repository minimo per configurare gli agenti AI

ant apply richiede la CLI 1.30.0 o successiva. Il quickstart ufficiale descrive l'installazione con Homebrew e l'accesso dal browser.

1. 1

   Installare ed eseguire l'autenticazione

   Installate la CLI, verificate la versione ed effettuate l'accesso:

   brew install anthropics/tap/ant
   ant --version
   ant auth login

2. 2

   Creare un file agente

   Create agents/summarizer.md con la definizione minima documentata:

   ---
   name: Summarizer
   model: claude-opus-5
   tools:
     - type: agent_toolset_20260401
   ---
   
   You are a helpful assistant that writes concise summaries.

3. 3

   Applicarlo una volta dalla radice del repository

   Eseguite il comando documentato per un singolo file:

   ant apply agents/summarizer.md

   Esaminate il piano, chiedete i dettagli se serve il diff campo per campo, quindi approvatelo. Se l'esecuzione riesce, viene creato l'agente remoto e claude-lock.json viene scritto accanto al progetto.

4. 4

   Separare anteprima e applicazione in job diversi

   Nelle pull request usate il comando di anteprima documentato:

   ant apply --dry-run .

   Dopo il merge, serializzate il job di deployment e applicate la directory indicata:

   ant apply --yes .

   Al termine versionate il lockfile aggiornato, anche dopo un errore di applicazione parziale: l'esecuzione potrebbe avere già creato alcune risorse e averle registrate.

La trappola del codice di uscita in CI

È un punto importante, perché il drift remoto fa parte della normale operatività. Qualcuno può modificare un agente dalla Console tra la review e il merge. L'anteprima dovrebbe trasformare l'evento in una decisione visibile, non in una casella verde che il job di deployment scoprirà troppo tardi.

Per il job di applicazione usate Workload Identity Federation invece di una chiave API memorizzata. Vincolate il job all'organizzazione e al workspace registrati nel lockfile e consentite una sola esecuzione di Apply alla volta.

I limiti, senza scorciatoie

Trattare i file come codice non rende gestibile ogni risorsa remota.

ant apply non può adottare un agente creato separatamente nella Console o con ant beta:agents create. Se i file e il lockfile provengono dalla funzione Export as code della Console, Apply può aggiornare le risorse esportate. In caso contrario, applicare un file corrispondente crea un'altra risorsa.

Anche l'eliminazione è prudente. Rimuovere un file lascia al suo posto la risorsa remota e produce un avviso. --prune elimina la risorsa remota; rinominare un file, invece, ne dichiara una nuova e conserva la precedente finché non viene eseguito il prune.

--force e --prune sono quindi controlli di produzione, non semplici comodità per fare pulizia. Metteteli entrambi dietro una review. Una rinomina sbagliata seguita da un prune automatico può eliminare la risorsa ancora attesa dal deployment.

Anche il lockfile diventa stato operativo condiviso. Va versionato dopo ogni Apply, proteggendone il branch e serializzando le scritture. Se un'esecuzione fallisce a metà, non scartate la modifica al lockfile soltanto perché il job è rosso.

Infine, si tratta ancora di un servizio beta. Claude Managed Agents è abilitato per impostazione predefinita negli account Claude API, ma i team che richiedono Zero Data Retention o HIPAA BAA incontrano un limite di prodotto che la review nel repository non può risolvere.

Cosa fare lunedì

Conviene agire questa settimana se più di una persona modifica le stesse risorse Managed Agents, se la medesima configurazione attraversa più ambienti o se i deployment pianificati richiedono un responsabile e una traccia di review.

Meglio aspettare se un solo operatore gestisce un esperimento stabile, se il costo misurato del passaggio di consegne è inferiore a quello della nuova review o se la policy sui dati richiede Zero Data Retention o la copertura HIPAA BAA.

Il cambiamento non incide sui team i cui agenti funzionano esclusivamente tramite Claude Code, l'app Claude o un loop personalizzato sulla Messages API senza risorse Claude Managed Agents.

Lunedì scegliete un agente non destinato alla produzione. Fate passare la sua definizione e il lockfile attraverso una vera pull request. Registrate i minuti necessari per il passaggio attuale e per il percorso sottoposto a review. Poi create una modifica remota nell'ambiente sicuro e verificate che il controllo della pull request tratti il piano bloccato come tale. Solo a quel punto ant apply --yes . dovrebbe essere eseguito dopo un merge.

Ricevi nella newsletter la prossima guida pratica ai workflow AI.