Gérer les ressources en tant que code avec ant apply

ant apply crée et met à jour des ressources de l'API Claude à partir de fichiers : agents, environnements, skills, magasins de mémoire et déploiements. Ces fichiers se trouvent dans votre dépôt et leurs modifications passent par la même revue que votre code. Vous décrivez chaque ressource dans un fichier, exécutez ant apply, puis approuvez le plan qu'il affiche. Vous commitez ensuite le fichier claude-lock.json qu'il écrit, afin que l'exécution suivante mette à jour les mêmes ressources au lieu d'en créer de nouvelles.

Pour installer et authentifier la CLI, consultez le guide de démarrage rapide de la CLI. ant apply nécessite la version 1.30.0 ou ultérieure de la CLI.

Appliquer votre premier agent

Écrivez l'agent sous forme de fichier Markdown dans agents/ et appliquez-le :

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.

Le « frontmatter » (en-tête de métadonnées) contient la configuration de l'agent (les champs de Définir votre agent) et le corps constitue son « system prompt » (invite système). ant apply déduit que le fichier est un agent à partir de son chemin, ici le répertoire agents/.

Dans un terminal interactif, ant apply affiche le plan et attend votre approbation :

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

Répondez d pour voir d'abord les détails : les champs de chaque nouvelle ressource, ou un diff champ par champ de chaque mise à jour. --dry-run affiche ce plan détaillé et se termine sans rien modifier.

Pour modifier l'agent, éditez le fichier et exécutez à nouveau ant apply. Le plan affiche alors une mise à jour au lieu d'une création.

Commiter claude-lock.json

Le premier ant apply écrit claude-lock.json, le « lockfile » (fichier de verrouillage), dans le répertoire depuis lequel vous l'exécutez ; exécutez-le donc depuis la racine du dépôt. Il enregistre l'ID de la ressource créée par chaque fichier ainsi que l'organisation et l'espace de travail dans lesquels se trouvent les ressources :

{
  "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"
    }
  }
}

Commitez-le avec vos fichiers. C'est grâce à lui que l'exécution suivante, sur votre machine ou en CI, retrouve ces ressources au lieu de les créer à nouveau, et c'est là que vous lisez l'ID d'un agent pour démarrer une session. Les deux hachages constituent une empreinte de ce qui a été envoyé en dernier et de ce que l'API a renvoyé. C'est ainsi qu'une exécution ultérieure détecte un fichier modifié, ou une ressource modifiée en dehors de ces fichiers.

Faire évoluer le tout en projet

Vous pouvez également définir de manière déclarative les autres ressources sous forme de fichiers. Un fichier contient le corps de requête que vous enverriez au point de terminaison de création de ce type :

• Un environnement est un fichier YAML dans environments/.
• Un magasin de mémoire est un fichier YAML dans memory_stores/.
• Un déploiement est un fichier Markdown dans deployments/ : le frontmatter est le corps de la requête et le texte devient le message qui démarre chaque session.
• Une skill est un répertoire avec un SKILL.md à sa racine, placé par convention dans skills/, et téléversé en un seul paquet.

Toute ressource, à l'exception d'une skill, peut être écrite en YAML, JSON ou Markdown. En Markdown, le frontmatter constitue le corps et le texte remplit le champ textuel du type : le system d'un agent, la description d'un environnement ou d'un magasin de mémoire, le premier message d'un déploiement.

Les ressources se référencent les unes les autres par chemin. Partout où l'API attend l'ID d'une autre ressource, écrivez plutôt le chemin relatif vers le fichier de cette ressource. Dans ce projet, l'agent reviewer liste ../skills/pr-summary sous skills, l'agent lead liste ./reviewer.md dans son équipe, et le déploiement désigne son agent, son environnement et son magasin de mémoire par leur chemin. ant apply les crée dans l'ordre des dépendances et renseigne les véritables ID. Le projet comporte six fichiers :

---
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.

Appliquez l'ensemble du répertoire :

ant apply .

claude-lock.json contient alors une entrée pour chaque fichier du projet.

Les chemins relatifs permettent à ces fichiers de pointer les uns vers les autres. ant apply épingle les références aux agents et aux skills à la version qu'il vient d'appliquer, de sorte que modifier reviewer.md ou la skill met à jour, lors de la même exécution, tout ce qui y fait référence. Un chemin fonctionne également à l'intérieur d'un objet, comme dans l'entrée resources du déploiement, où les autres clés telles que access sont conservées.

Pour pointer vers une ressource que ces fichiers ne gèrent pas, écrivez plutôt son ID (agent_..., skill_...). Tout le reste, comme {type: anthropic, skill_id: xlsx}, est envoyé à l'API tel quel. Une référence de skill peut également être une URL GitHub de la forme https://github.com/<owner>/<repo>/tree/<branch>/<dir>, par exemple un répertoire du dépôt de skills open source d'Anthropic : ant apply télécharge puis téléverse ce répertoire, épinglé au commit résolu jusqu'à ce que vous l'exécutiez avec --upgrade (définissez GITHUB_TOKEN pour un dépôt privé).

Comment ant apply déduit le type d'un fichier

Lorsque ant apply parcourt un répertoire, il détermine le type de chaque fichier à partir du premier des critères suivants qui correspond :

1. Un champ type de premier niveau dans le fichier.
2. Le répertoire dans lequel se trouve directement le fichier : agents/, environments/, memory_stores/ ou deployments/.
3. Un nom de fichier qui commence par le type, comme environment_staging.md.

Il ignore les fichiers qui ne correspondent à aucun de ces critères, comme les README et la configuration CI, sauf si vous les nommez sur la ligne de commande. Un fichier Markdown nommé qui ne correspond à aucun critère est traité comme un agent, et un fichier YAML ou JSON nommé qui ne correspond à aucun critère provoque une erreur.

Modifier et réappliquer

Exécuter ant apply sans arguments réconcilie chaque fichier suivi par le lockfile. Dans un terminal, il liste également les fichiers de ressources non suivis situés sous le répertoire du lockfile et propose de les ajouter. Supprimer un champ d'un fichier l'efface sur la ressource si l'API permet d'effacer ce champ. Un champ que vous n'avez jamais défini, ou que l'API ne peut pas effacer, conserve sa valeur actuelle.

Si une ressource a été modifiée, archivée ou supprimée en dehors de ces fichiers (dans la Claude Console, par exemple), le plan se termine par This plan cannot be applied: suivi de la raison. La commande se termine alors avec refusing to apply. Passez --force pour écraser la modification ou créer une ressource de remplacement.

Supprimer un fichier laisse sa ressource en place avec un avertissement, et --prune la supprime (en l'archivant, ou en la supprimant dans le cas d'une skill). Renommer un fichier déclare donc une nouvelle ressource et laisse l'ancienne en place jusqu'à ce que vous fassiez un nettoyage avec --prune.

ant apply ne peut pas prendre en charge une ressource que vous avez créée dans la Console ou avec ant beta:agents create. Seul ce qui figure dans le lockfile est géré, et appliquer un fichier qui décrit un agent existant en crée un second. Si vous avez téléchargé votre agent depuis la Console avec Export as code, le téléchargement inclut son propre claude-lock.json, de sorte que l'appliquer met à jour les ressources que vous y avez créées.

Exécuter ant apply en CI

Sans terminal, ant apply affiche le plan et s'arrête avec cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan only. Configurez la CI comme suit :

• Exécutez ant apply --yes . sur votre branche par défaut après la fusion, en nommant le répertoire du projet. Un simple ant apply --yes ne réconcilie que les fichiers déjà suivis par le lockfile et ignore un fichier nouvellement ajouté.
• Sur les pull requests, exécutez ant apply --dry-run . pour afficher le plan à l'intention des relecteurs. Cette commande est purement informative et se termine avec le code 0 même lorsque le plan est bloqué.
• Commitez le claude-lock.json mis à jour à la fin du job, même lorsque l'étape d'application a échoué en cours de route, car une application partielle enregistre tout de même ce qu'elle a créé.
• Exécutez une seule application à la fois, car rien ne verrouille le lockfile.
• Authentifiez-vous avec Workload Identity Federation plutôt qu'avec une clé API stockée, en tant qu'identité ayant accès à l'organisation et à l'espace de travail enregistrés dans claude-lock.json. ant apply refuse les identifiants qui correspondent à toute autre organisation ou tout autre espace de travail.

Pour un workflow GitHub Actions complet, consultez l'exemple CI dans le README de la CLI.

Options

Étapes suivantes