Ressourcen als Code mit ant apply verwalten

ant apply erstellt und aktualisiert Claude-API-Ressourcen aus Dateien: Agenten, Umgebungen, Skills, Memory Stores und Deployments. Sie liegen in deinem Repository und durchlaufen bei Änderungen dasselbe Review wie dein Code. Du beschreibst jede Ressource in einer Datei, führst ant apply aus und bestätigst den angezeigten Plan. Anschließend committest du die geschriebene claude-lock.json, damit der nächste Lauf dieselben Ressourcen aktualisiert, statt neue zu erstellen.

Informationen zur Installation und Authentifizierung der CLI findest du im CLI-Schnellstart. ant apply erfordert CLI-Version 1.30.0 oder höher.

Deinen ersten Agenten anwenden

Schreibe den Agenten als Markdown-Datei unter agents/ und wende ihn an:

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.

Das Frontmatter enthält die Konfiguration des Agenten (die Felder aus Deinen Agenten definieren), und der Textkörper ist sein System-Prompt. ant apply leitet anhand des Pfads ab, dass die Datei ein Agent ist, hier anhand des Verzeichnisses agents/.

In einem interaktiven Terminal gibt ant apply den Plan aus und wartet auf deine Bestätigung:

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

Antworte mit d, um zuerst Details zu sehen: die Felder jeder neuen Ressource oder einen feldweisen Diff jeder Aktualisierung. --dry-run gibt diesen detaillierten Plan aus und beendet sich, ohne etwas zu ändern.

Um den Agenten zu ändern, bearbeite die Datei und führe ant apply erneut aus. Der Plan zeigt dann eine Aktualisierung statt einer Erstellung.

claude-lock.json committen

Das erste ant apply schreibt claude-lock.json, das „lockfile" (Sperrdatei), in das Verzeichnis, aus dem du es ausführst. Führe es daher aus dem Stammverzeichnis des Repositorys aus. Es speichert die ID der Ressource, die jede Datei erstellt hat, sowie die Organisation und den Workspace, in denen sich die Ressourcen befinden:

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

Committe es zusammen mit deinen Dateien. Darüber findet der nächste Lauf, auf deinem Rechner oder in CI, diese Ressourcen, statt sie erneut zu erstellen, und dort liest du die ID eines Agenten ab, um eine Sitzung zu starten. Die beiden Hashes sind Fingerabdrücke dessen, was zuletzt gesendet wurde, und dessen, was die API zurückgegeben hat. So bemerkt ein späterer Lauf eine bearbeitete Datei oder eine Ressource, die außerhalb dieser Dateien geändert wurde.

Zu einem Projekt ausbauen

Du kannst auch die anderen Ressourcen deklarativ als Dateien definieren. Eine Datei enthält den Request-Body, den du an den Create-Endpunkt der jeweiligen Ressourcenart senden würdest:

• Eine Umgebung ist eine YAML-Datei in environments/.
• Ein Memory Store ist eine YAML-Datei in memory_stores/.
• Ein Deployment ist eine Markdown-Datei in deployments/: Das Frontmatter ist der Request-Body, und der Fließtext wird zur Nachricht, mit der jede Sitzung beginnt.
• Ein Skill ist ein Verzeichnis mit einer SKILL.md im Stammverzeichnis, üblicherweise unter skills/, das als ein Bundle hochgeladen wird.

Jede Ressource außer einem Skill kann als YAML, JSON oder Markdown geschrieben werden. In Markdown ist das Frontmatter der Body, und der Fließtext füllt das Textfeld der jeweiligen Ressourcenart: das system eines Agenten, die description einer Umgebung oder eines Memory Stores, die erste Nachricht eines Deployments.

Ressourcen verweisen über Pfade aufeinander. Überall dort, wo die API die ID einer anderen Ressource erwartet, schreibst du stattdessen den relativen Pfad zur Datei dieser Ressource. In diesem Projekt listet der Reviewer-Agent ../skills/pr-summary unter skills auf, der Lead-Agent listet ./reviewer.md in seinem Roster auf, und das Deployment benennt seinen Agenten, seine Umgebung und seinen Memory Store über Pfade. ant apply erstellt sie in der Reihenfolge ihrer Abhängigkeiten und setzt die echten IDs ein. Das Projekt besteht aus sechs Dateien:

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

Wende das gesamte Verzeichnis an:

ant apply .

claude-lock.json enthält dann einen Eintrag für jede Datei im Projekt.

Über relative Pfade verweisen diese Dateien aufeinander. ant apply fixiert Agenten- und Skill-Referenzen auf die gerade angewendete Version, sodass das Bearbeiten von reviewer.md oder des Skills im selben Lauf alles aktualisiert, was darauf verweist. Ein Pfad funktioniert auch innerhalb eines Objekts, wie im resources-Eintrag des Deployments, wobei die anderen Schlüssel wie access erhalten bleiben.

Um auf eine Ressource zu verweisen, die nicht von diesen Dateien verwaltet wird, schreibe stattdessen ihre ID (agent_..., skill_...). Alles andere, etwa {type: anthropic, skill_id: xlsx}, wird unverändert an die API gesendet. Eine Skill-Referenz kann auch eine GitHub-URL der Form https://github.com/<owner>/<repo>/tree/<branch>/<dir> sein, zum Beispiel ein Verzeichnis aus Anthropics Open-Source-Skills-Repository: ant apply lädt dieses Verzeichnis herunter und wieder hoch, fixiert auf den aufgelösten Commit, bis du mit --upgrade ausführst (setze GITHUB_TOKEN für ein privates Repository).

Wie ant apply die Ressourcenart einer Datei ableitet

Wenn ant apply ein Verzeichnis durchläuft, bestimmt es die Ressourcenart jeder Datei anhand des ersten zutreffenden Kriteriums:

1. Ein type-Feld auf oberster Ebene in der Datei.
2. Das Verzeichnis, in dem die Datei direkt liegt: agents/, environments/, memory_stores/ oder deployments/.
3. Ein Dateiname, der mit der Ressourcenart beginnt, etwa environment_staging.md.

Dateien, auf die keines dieser Kriterien zutrifft, etwa READMEs und CI-Konfiguration, werden übersprungen, es sei denn, du gibst sie in der Befehlszeile an. Eine explizit angegebene Markdown-Datei, auf die keines zutrifft, wird als Agent behandelt, und eine explizit angegebene YAML- oder JSON-Datei, auf die keines zutrifft, führt zu einem Fehler.

Bearbeiten und erneut anwenden

Wenn du ant apply ohne Argumente ausführst, werden alle Dateien abgeglichen, die das Lockfile verfolgt. In einem Terminal listet es außerdem nicht verfolgte Ressourcendateien unterhalb des Lockfile-Verzeichnisses auf und bietet an, sie hinzuzufügen. Wenn du ein Feld aus einer Datei löschst, wird es in der Ressource geleert, sofern die API das Leeren dieses Felds erlaubt. Ein Feld, das du nie gesetzt hast oder das die API nicht leeren kann, behält seinen aktuellen Wert.

Wenn eine Ressource außerhalb dieser Dateien bearbeitet, archiviert oder gelöscht wurde (zum Beispiel in der Claude Console), endet der Plan mit This plan cannot be applied: und dem Grund. Der Befehl beendet sich dann mit refusing to apply. Übergib --force, um die Änderung zu überschreiben oder einen Ersatz zu erstellen.

Wenn du eine Datei löschst, bleibt ihre Ressource mit einer Warnung bestehen, und --prune entfernt sie (archiviert sie bzw. löscht sie bei einem Skill). Das Umbenennen einer Datei deklariert daher eine neue Ressource und lässt die alte bestehen, bis du sie mit Prune entfernst.

ant apply kann keine Ressource übernehmen, die du in der Console oder mit ant beta:agents create erstellt hast. Verwaltet wird nur, was im Lockfile steht, und das Anwenden einer Datei, die einen bestehenden Agenten beschreibt, erstellt einen zweiten. Wenn du deinen Agenten über Export as code aus der Console heruntergeladen hast, enthält der Download eine eigene claude-lock.json, sodass beim Anwenden die Ressourcen aktualisiert werden, die du dort erstellt hast.

ant apply in CI ausführen

Ohne Terminal gibt ant apply den Plan aus und stoppt mit cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan only. Richte CI wie folgt ein:

• Führe nach dem Merge auf deinem Standard-Branch ant apply --yes . aus und gib dabei das Projektverzeichnis an. Ein bloßes ant apply --yes gleicht nur Dateien ab, die das Lockfile bereits verfolgt, und überspringt neu hinzugefügte.
• Führe bei Pull Requests ant apply --dry-run . aus, um den Plan für Reviewer auszugeben. Dies dient nur zur Information und beendet sich mit 0, selbst wenn der Plan blockiert ist.
• Committe die aktualisierte claude-lock.json am Ende des Jobs, auch wenn der Apply-Schritt mittendrin fehlgeschlagen ist, denn ein teilweises Apply speichert trotzdem, was es erstellt hat.
• Führe jeweils nur ein Apply gleichzeitig aus, da nichts das Lockfile sperrt.
• Authentifiziere dich mit Workload Identity Federation statt mit einem gespeicherten API-Key, und zwar als Identität, die Zugriff auf die in claude-lock.json gespeicherte Organisation und den Workspace hat. ant apply lehnt Anmeldedaten ab, die zu einer anderen Organisation oder einem anderen Workspace gehören.

Einen vollständigen GitHub-Actions-Workflow findest du im CI-Beispiel in der CLI-README.

Flags

Nächste Schritte