Gestisci le risorse come codice con ant apply

ant apply crea e aggiorna le risorse della Claude API a partire da file: agenti, ambienti, skill, archivi di memoria e deployment. Queste risorse risiedono nel tuo repository e vengono modificate attraverso la stessa revisione del tuo codice. Descrivi ogni risorsa in un file, esegui ant apply e approva il piano che mostra. Poi esegui il commit del file claude-lock.json che scrive, in modo che l'esecuzione successiva aggiorni le stesse risorse invece di crearne di nuove.

Per installare e autenticare la CLI, consulta la guida rapida della CLI. ant apply richiede la versione 1.30.0 o successiva della CLI.

Applica il tuo primo agente

Scrivi l'agente come file Markdown in agents/ e applicalo:

ant apply agents/summarizer.md

---
name: Summarizer
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful assistant that writes concise summaries.

Il "frontmatter" (intestazione di metadati) contiene la configurazione dell'agente (i campi di Definisci il tuo agente) e il corpo è il suo "system prompt" (prompt di sistema). ant apply deduce che il file è un agente dal suo percorso, in questo caso la directory agents/.

In un terminale interattivo, ant apply stampa il piano e attende la tua approvazione:

First apply  ./claude-lock.json does not exist yet and will be created

Resources will be created with
  credentials   API key (--api-key / ANTHROPIC_API_KEY)
  host          api.anthropic.com
  organization  1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f
  workspace     wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

Preview  ./claude-lock.json (new)

± Name                    Plan
+ ./agents/summarizer.md  create

Resources  + 1 to create

Apply these changes? (y)es / (n)o / (d)etails y

Apply  ./claude-lock.json

± Name                    Status
+ ./agents/summarizer.md  created    agent_011CYm1BLqPXpQRk5khsSXrs

Resources  + 1 created

State written to ./claude-lock.json

Rispondi d per vedere prima i dettagli: i campi di ogni nuova risorsa, oppure un diff campo per campo di ogni aggiornamento. --dry-run stampa quel piano dettagliato ed esce senza modificare nulla.

Per modificare l'agente, modifica il file ed esegui di nuovo ant apply. Il piano mostrerà quindi un aggiornamento invece di una creazione.

Esegui il commit di claude-lock.json

Il primo ant apply scrive claude-lock.json, il "lockfile" (file di blocco), nella directory da cui lo esegui, quindi eseguilo dalla radice del repository. Registra l'ID della risorsa creata da ciascun file e l'organizzazione e il workspace in cui risiedono le risorse:

{
  "version": 1,
  "origin": {
    "base_url": "https://api.anthropic.com",
    "organization_id": "1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f",
    "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  },
  "resources": {
    "./agents/summarizer.md": {
      "kind": "agent",
      "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "version": "1",
      "hash": "d23251c8d99b3613a64f3f8d87f5fad4",
      "remote_hash": "1b771bee5bdbf600a5ad972fdac32d94"
    }
  }
}

Esegui il commit insieme ai tuoi file. È il modo in cui l'esecuzione successiva, sulla tua macchina o in CI, trova queste risorse invece di crearle di nuovo, ed è il punto in cui leggi l'ID di un agente per avviare una sessione. I due hash costituiscono un'impronta di ciò che è stato inviato per ultimo e di ciò che l'API ha restituito. È così che un'esecuzione successiva rileva un file modificato, o una risorsa modificata al di fuori di questi file.

Espandilo in un progetto

Puoi definire in modo dichiarativo anche le altre risorse come file. Un file contiene il corpo della richiesta che invieresti all'endpoint di creazione di quel tipo:

• Un ambiente è un file YAML in environments/.
• Un archivio di memoria è un file YAML in memory_stores/.
• Un deployment è un file Markdown in deployments/: il frontmatter è il corpo della richiesta e il testo diventa il messaggio che avvia ogni sessione.
• Una skill è una directory con un SKILL.md nella sua radice, per convenzione in skills/, caricata come un unico pacchetto.

Qualsiasi risorsa tranne una skill può essere scritta in YAML, JSON o Markdown. In Markdown, il frontmatter è il corpo e il testo riempie il campo di testo del tipo: il system di un agente, la description di un ambiente o di un archivio di memoria, il primo messaggio di un deployment.

Le risorse fanno riferimento l'una all'altra tramite percorso. Ovunque l'API si aspetti l'ID di un'altra risorsa, scrivi invece il percorso relativo al file di quella risorsa. In questo progetto, l'agente revisore elenca ../skills/pr-summary in skills, l'agente principale elenca ./reviewer.md nel suo elenco di agenti, e il deployment indica il suo agente, ambiente e archivio di memoria tramite percorso. ant apply li crea in ordine di dipendenza e inserisce gli ID reali. Il progetto ha sei file:

---
name: Code reviewer
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
skills:
  - ../skills/pr-summary
---

You review pull requests for correctness, security, and readability.

---
name: Engineering lead
model: claude-opus-5
multiagent:
  type: coordinator
  agents:
    - ./reviewer.md
---

You coordinate engineering work. Delegate code review to the reviewer.

---
name: pr-summary
description: Summarize a pull request's changes and risks in the team's review format.
---

# PR summary

List what changed, why, and anything a reviewer should look at closely, in three short sections.

name: review-env
description: Cloud container with unrestricted networking for review sessions.
config:
  type: cloud
  networking:
    type: unrestricted

name: Review notes
description: Recurring issues and house-style decisions the reviewer has recorded between runs.

---
name: Nightly review
agent: ../agents/reviewer.md # the API's agent field: sent as {type: agent, id, version}
environment_id: ../environments/cloud.yaml # sent as the environment's ID
resources:
  - path: ../memory_stores/review-notes.yaml
    access: read_write
schedule:
  type: cron
  expression: "0 3 * * *"
  timezone: America/Los_Angeles
---

Review any open pull requests. Start with the oldest.

Applica l'intera directory:

ant apply .

claude-lock.json avrà quindi una voce per ogni file del progetto.

I percorsi relativi sono il modo in cui questi file puntano l'uno all'altro. ant apply fissa i riferimenti ad agenti e skill alla versione appena applicata, quindi modificare reviewer.md o la skill aggiorna tutto ciò che vi fa riferimento nella stessa esecuzione. Un percorso funziona anche all'interno di un oggetto, come nella voce resources del deployment, dove le altre chiavi come access vengono mantenute.

Per puntare a una risorsa che questi file non gestiscono, scrivi invece il suo ID (agent_..., skill_...). Qualsiasi altra cosa, come {type: anthropic, skill_id: xlsx}, viene inviata all'API così come è scritta. Un riferimento a una skill può anche essere un URL GitHub nella forma https://github.com/<owner>/<repo>/tree/<branch>/<dir>, ad esempio una directory del repository di skill open source di Anthropic: ant apply scarica e carica quella directory, fissata al commit risolto finché non esegui con --upgrade (imposta GITHUB_TOKEN per un repository privato).

Come ant apply deduce il tipo di un file

Quando ant apply esplora una directory, determina il tipo di ciascun file in base al primo dei seguenti criteri che corrisponde:

1. Un campo type di primo livello nel file.
2. La directory in cui si trova direttamente il file: agents/, environments/, memory_stores/ o deployments/.
3. Un nome di file che inizia con il tipo, come environment_staging.md.

Salta i file che non corrispondono a nessuno di questi criteri, come i README e la configurazione CI, a meno che tu non li indichi sulla riga di comando. Un file Markdown indicato esplicitamente che non corrisponde a nessun criterio viene trattato come un agente, mentre un file YAML o JSON indicato esplicitamente che non corrisponde a nessun criterio genera un errore.

Modifica e riapplica

Eseguire ant apply senza argomenti riconcilia ogni file tracciato dal lockfile. In un terminale, elenca anche i file di risorse non tracciati nella directory del lockfile e propone di aggiungerli. Eliminare un campo da un file lo cancella sulla risorsa se l'API consente di cancellare quel campo. Un campo che non hai mai impostato, o uno che l'API non può cancellare, mantiene il suo valore attuale.

Se una risorsa è stata modificata, archiviata o eliminata al di fuori di questi file (nella Claude Console, ad esempio), il piano termina con This plan cannot be applied: e il motivo. Il comando esce quindi con refusing to apply. Passa --force per sovrascrivere la modifica o creare una sostituzione.

Eliminare un file lascia la sua risorsa al suo posto con un avviso, e --prune la rimuove (archiviandola, o eliminandola nel caso di una skill). Rinominare un file dichiara quindi una nuova risorsa e lascia quella vecchia al suo posto finché non esegui la rimozione.

ant apply non può adottare una risorsa che hai creato nella Console o con ant beta:agents create. Viene gestito solo ciò che si trova nel lockfile, e applicare un file che descrive un agente esistente ne crea un secondo. Se hai scaricato il tuo agente dalla Console con Export as code, il download include il proprio claude-lock.json, quindi applicarlo aggiorna le risorse che hai creato lì.

Esegui ant apply in CI

Senza un terminale, ant apply stampa il piano e si ferma con cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan only. Configura la CI come segue:

• Esegui ant apply --yes . sul tuo branch predefinito dopo il merge, indicando la directory del progetto. Un semplice ant apply --yes riconcilia solo i file già tracciati dal lockfile e salta quelli appena aggiunti.
• Sulle pull request, esegui ant apply --dry-run . per stampare il piano per i revisori. È solo informativo ed esce con 0 anche quando il piano è bloccato.
• Esegui il commit del claude-lock.json aggiornato alla fine del job, anche quando il passaggio di applicazione è fallito a metà, perché un'applicazione parziale registra comunque ciò che ha creato.
• Esegui un'applicazione alla volta, perché nulla blocca il lockfile.
• Autenticati con Workload Identity Federation anziché con una chiave API memorizzata, come un'identità che ha accesso all'organizzazione e al workspace registrati in claude-lock.json. ant apply rifiuta le credenziali che si risolvono in qualsiasi altra organizzazione o workspace.

Per un workflow GitHub Actions completo, consulta l'esempio CI nel README della CLI.

Flag

Passaggi successivi