Gestiona recursos como código con ant apply

ant apply crea y actualiza recursos de la API de Claude a partir de archivos: agentes, entornos, "skills" (habilidades), almacenes de memoria y despliegues. Estos recursos viven en tu repositorio y sus cambios pasan por la misma revisión que tu código. Describes cada recurso en un archivo, ejecutas ant apply y apruebas el plan que muestra. Luego haces commit del claude-lock.json que genera, para que la siguiente ejecución actualice los mismos recursos en lugar de crear otros nuevos.

Para instalar y autenticar la CLI, consulta el inicio rápido de la CLI. ant apply requiere la versión 1.30.0 o posterior de la CLI.

Aplica tu primer agente

Escribe el agente como un archivo Markdown en agents/ y aplícalo:

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.

El "frontmatter" (encabezado de metadatos) contiene la configuración del agente (los campos de Define tu agente) y el cuerpo es su "system prompt" (indicación del sistema). ant apply infiere que el archivo es un agente a partir de su ruta, en este caso el directorio agents/.

En una terminal interactiva, ant apply imprime el plan y espera tu aprobación:

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

Responde d para ver primero los detalles: los campos de cada recurso nuevo o un diff campo por campo de cada actualización. --dry-run imprime ese plan detallado y termina sin cambiar nada.

Para cambiar el agente, edita el archivo y vuelve a ejecutar ant apply. El plan mostrará entonces una actualización en lugar de una creación.

Haz commit de claude-lock.json

El primer ant apply escribe claude-lock.json, el "lockfile" (archivo de bloqueo), en el directorio desde el que lo ejecutas, así que ejecútalo desde la raíz del repositorio. Este archivo registra el ID del recurso que creó cada archivo, así como la organización y el espacio de trabajo en los que viven los recursos:

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

Haz commit de él junto con tus archivos. Gracias a él, la siguiente ejecución, ya sea en tu máquina o en "continuous integration" (integración continua), o CI, encuentra estos recursos en lugar de volver a crearlos. También es donde consultas el ID de un agente para iniciar una sesión. Los dos hashes son huellas de lo último que se envió y de lo que devolvió la API. Así es como una ejecución posterior detecta un archivo editado o un recurso modificado fuera de estos archivos.

Amplíalo a un proyecto

También puedes definir de forma declarativa los demás recursos como archivos. Cada archivo contiene el cuerpo de la solicitud que enviarías al endpoint de creación de ese tipo de recurso:

• Un entorno es un archivo YAML en environments/.
• Un almacén de memoria es un archivo YAML en memory_stores/.
• Un despliegue es un archivo Markdown en deployments/: el frontmatter es el cuerpo de la solicitud y la prosa se convierte en el mensaje que inicia cada sesión.
• Una skill es un directorio con un SKILL.md en su raíz, por convención dentro de skills/, que se sube como un solo paquete.

Cualquier recurso, excepto una skill, puede escribirse en YAML, JSON o Markdown. En Markdown, el frontmatter es el cuerpo y la prosa rellena el campo de texto correspondiente a cada tipo: el system de un agente, la description de un entorno o de un almacén de memoria, o el primer mensaje de un despliegue.

Los recursos se referencian entre sí mediante rutas. Dondequiera que la API espere el ID de otro recurso, escribe en su lugar la ruta relativa al archivo de ese recurso. En este proyecto, el agente revisor incluye ../skills/pr-summary en skills, el agente principal incluye ./reviewer.md en su lista de agentes, y el despliegue indica su agente, su entorno y su almacén de memoria mediante rutas. ant apply los crea en orden de dependencias y completa los IDs reales. El proyecto tiene seis archivos:

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

Aplica todo el directorio:

ant apply .

A continuación, claude-lock.json tendrá una entrada para cada archivo del proyecto.

Las rutas relativas son la forma en que estos archivos se referencian entre sí. ant apply fija las referencias a agentes y skills a la versión que acaba de aplicar, por lo que editar reviewer.md o la skill actualiza, en la misma ejecución, todo lo que hace referencia a ellos. Una ruta también funciona dentro de un objeto, como en la entrada resources del despliegue, donde se conservan las demás claves, como access.

Para apuntar a un recurso que estos archivos no gestionan, escribe su ID (agent_..., skill_...) en su lugar. Cualquier otro valor, como {type: anthropic, skill_id: xlsx}, se envía a la API tal como está escrito. Una referencia a una skill también puede ser una URL de GitHub con el formato https://github.com/<owner>/<repo>/tree/<branch>/<dir>, por ejemplo, un directorio del repositorio de skills de código abierto de Anthropic. En ese caso, ant apply descarga y sube ese directorio, fijado al commit resuelto hasta que ejecutes el comando con --upgrade (establece GITHUB_TOKEN si se trata de un repositorio privado).

Cómo infiere ant apply el tipo de un archivo

Cuando ant apply recorre un directorio, determina el tipo de cada archivo según el primero de estos criterios que se cumpla:

1. Un campo type de nivel superior en el archivo.
2. El directorio que contiene directamente al archivo: agents/, environments/, memory_stores/ o deployments/.
3. Un nombre de archivo que empieza con el tipo, como environment_staging.md.

Omite los archivos que no cumplen ninguno de estos criterios, como los README y la configuración de CI, a menos que los indiques en la línea de comandos. Un archivo Markdown indicado explícitamente que no cumple ninguno se trata como un agente, mientras que un archivo YAML o JSON indicado explícitamente que no cumple ninguno produce un error.

Edita y vuelve a aplicar

Ejecutar ant apply sin argumentos reconcilia todos los archivos que rastrea el lockfile. En una terminal, también lista los archivos de recursos no rastreados dentro del directorio del lockfile y ofrece agregarlos. Si eliminas un campo de un archivo, ese campo se borra en el recurso siempre que la API permita borrarlo. Un campo que nunca estableciste, o uno que la API no puede borrar, conserva su valor actual.

Si un recurso se editó, archivó o eliminó fuera de estos archivos (por ejemplo, en la Claude Console), el plan termina con This plan cannot be applied: seguido del motivo. A continuación, el comando termina con refusing to apply. Usa --force para sobrescribir la edición o crear un reemplazo.

Si eliminas un archivo, su recurso se conserva y se muestra una advertencia; --prune lo elimina (lo archiva o, en el caso de una skill, lo borra). Por lo tanto, renombrar un archivo declara un recurso nuevo y conserva el anterior hasta que ejecutes el comando con --prune.

ant apply no puede adoptar un recurso que creaste en la Console o con ant beta:agents create. Solo se gestiona lo que está en el lockfile, y aplicar un archivo que describe un agente existente crea un segundo agente. Si descargaste tu agente desde la Console con Export as code, la descarga incluye su propio claude-lock.json, por lo que al aplicarlo se actualizan los recursos que creaste allí.

Ejecuta ant apply en CI

Sin una terminal, ant apply imprime el plan y se detiene con cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan only. Configura CI de la siguiente manera:

• Ejecuta ant apply --yes . en tu rama predeterminada después del merge, indicando el directorio del proyecto. Un ant apply --yes sin argumentos solo reconcilia los archivos que el lockfile ya rastrea y omite los que se hayan agregado recientemente.
• En los "pull requests" (solicitudes de incorporación de cambios), ejecuta ant apply --dry-run . para imprimir el plan para los revisores. Es solo informativo y termina con código 0 incluso cuando el plan está bloqueado.
• Haz commit del claude-lock.json actualizado al final del trabajo, incluso si el paso de aplicación falló a mitad de camino, porque una aplicación parcial igualmente registra lo que creó.
• Ejecuta una sola aplicación a la vez, porque nada bloquea el lockfile.
• Autentícate con Workload Identity Federation en lugar de con una clave de API almacenada, usando una identidad con acceso a la organización y al espacio de trabajo registrados en claude-lock.json. ant apply rechaza las credenciales que correspondan a cualquier otra organización o espacio de trabajo.

Para ver un flujo de trabajo completo de GitHub Actions, consulta el ejemplo de CI en el README de la CLI.

Opciones

Próximos pasos