Управление ресурсами как кодом с помощью ant apply

ant apply создает и обновляет ресурсы Claude API на основе файлов: агентов, окружения, навыки, хранилища памяти и развертывания. Эти файлы хранятся в вашем репозитории и проходят то же ревью, что и ваш код. Вы описываете каждый ресурс в файле, запускаете ant apply и одобряете показанный план. Затем вы фиксируете (commit) записанный командой файл claude-lock.json. Благодаря этому следующий запуск обновит те же ресурсы, а не создаст новые.

Об установке «command-line interface» (интерфейса командной строки), или CLI, и аутентификации в нем см. краткое руководство по CLI. Для ant apply требуется CLI версии 1.30.0 или новее.

Примените своего первого агента

Опишите агента в файле Markdown в каталоге agents/ и примените его:

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.

«Frontmatter» (блок метаданных в начале файла) содержит конфигурацию агента (поля из раздела Определение агента), а тело файла — его «system prompt» (системная подсказка). ant apply определяет по пути файла, что это агент: в данном случае по каталогу agents/.

В интерактивном терминале ant apply выводит план и ожидает вашего одобрения:

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

Ответьте d, чтобы сначала просмотреть подробности: поля каждого нового ресурса или построчное сравнение полей для каждого обновления. Флаг --dry-run выводит этот подробный план и завершает работу, ничего не изменяя.

Чтобы изменить агента, отредактируйте файл и снова запустите ant apply. На этот раз план покажет обновление, а не создание.

Зафиксируйте claude-lock.json

Первый запуск ant apply записывает claude-lock.json — «lockfile» (файл блокировки) — в каталог, из которого выполняется команда. Поэтому запускайте ее из корня репозитория. В файле записываются ID ресурса, созданного по каждому файлу, а также организация и рабочее пространство, в которых находятся ресурсы:

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

Зафиксируйте его вместе с вашими файлами. По нему следующий запуск находит эти ресурсы и не создает их заново — как на вашей машине, так и в «continuous integration» (непрерывной интеграции), или CI. Кроме того, в нем можно найти ID агента, чтобы начать сессию. Два хэша служат отпечатками того, что было отправлено в последний раз, и того, что вернул API. По ним последующий запуск замечает отредактированный файл или ресурс, измененный вне этих файлов.

Расширьте конфигурацию до проекта

Остальные ресурсы тоже можно декларативно описать в файлах. Файл содержит тело запроса, которое вы отправили бы в эндпоинт создания ресурса этого типа:

• Окружение — это файл YAML в каталоге environments/.
• Хранилище памяти — это файл YAML в каталоге memory_stores/.
• Развертывание — это файл Markdown в каталоге deployments/: frontmatter служит телом запроса, а текст становится сообщением, с которого начинается каждая сессия.
• Навык — это каталог с файлом SKILL.md в корне. По соглашению он размещается в skills/ и загружается единым пакетом.

Любой ресурс, кроме навыка, можно описать в формате YAML, JSON или Markdown. В Markdown frontmatter служит телом запроса, а текст заполняет текстовое поле ресурса соответствующего типа: system агента, description окружения или хранилища памяти, первое сообщение развертывания.

Ресурсы ссылаются друг на друга по пути. Везде, где API ожидает ID другого ресурса, укажите вместо него относительный путь к файлу этого ресурса. В этом проекте агент-рецензент указывает ../skills/pr-summary в поле skills, ведущий агент указывает ./reviewer.md в списке своих агентов, а развертывание ссылается на свои агент, окружение и хранилище памяти по пути. ant apply создает ресурсы в порядке зависимостей и подставляет реальные ID. Проект состоит из шести файлов:

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

Примените весь каталог:

ant apply .

После этого в claude-lock.json появится запись для каждого файла проекта.

Файлы ссылаются друг на друга через относительные пути. ant apply привязывает ссылки на агентов и навыки к только что примененной версии. Поэтому при редактировании reviewer.md или навыка в том же запуске обновляется все, что на них ссылается. Путь можно указать и внутри объекта, как в записи resources развертывания; остальные ключи, например access, при этом сохраняются.

Чтобы сослаться на ресурс, которым эти файлы не управляют, укажите вместо пути его ID (agent_..., skill_...). Все остальное, например {type: anthropic, skill_id: xlsx}, отправляется в API без изменений. Ссылкой на навык также может быть URL GitHub вида https://github.com/<owner>/<repo>/tree/<branch>/<dir> — например, каталог в открытом репозитории навыков Anthropic. ant apply скачивает этот каталог и загружает его в API. Версия закрепляется за коммитом, определенным при первом запуске, пока вы не запустите команду с флагом --upgrade. Для приватного репозитория задайте переменную GITHUB_TOKEN.

Как ant apply определяет тип файла

При обходе каталога ant apply определяет тип каждого файла по первому подходящему признаку из списка:

1. Поле type верхнего уровня в файле.
2. Каталог, в котором непосредственно находится файл: agents/, environments/, memory_stores/ или deployments/.
3. Имя файла, начинающееся с названия типа, например environment_staging.md.

Файлы, не подходящие ни под один признак (например, README и конфигурация CI), пропускаются, если вы не укажете их в командной строке явно. Явно указанный файл Markdown без подходящего признака считается агентом, а явно указанный файл YAML или JSON без подходящего признака вызывает ошибку.

Редактирование и повторное применение

При запуске без аргументов ant apply синхронизирует все файлы, отслеживаемые файлом блокировки. В терминале команда также выводит неотслеживаемые файлы ресурсов в каталоге файла блокировки и предлагает их добавить. Если удалить поле из файла, оно очищается и в ресурсе, если API позволяет очистить это поле. Поле, которое вы никогда не задавали или которое API не позволяет очистить, сохраняет текущее значение.

Если ресурс был отредактирован, архивирован или удален вне этих файлов (например, в Claude Console), план завершается строкой This plan cannot be applied: с указанием причины. Затем команда завершается с сообщением refusing to apply. Передайте флаг --force, чтобы перезаписать внешние изменения или создать ресурс заново.

Если удалить файл, его ресурс остается на месте, а команда выводит предупреждение. Флаг --prune удаляет такой ресурс: архивирует его, а навык удаляет полностью. Поэтому переименованный файл объявляет новый ресурс, а старый остается на месте, пока вы не выполните очистку.

ant apply не может взять под управление ресурс, созданный в Console или с помощью ant beta:agents create. Команда управляет только ресурсами из файла блокировки, поэтому применение файла с описанием существующего агента создаст второго агента. Если вы скачали агента из Console с помощью Export as code, архив содержит собственный claude-lock.json. Поэтому при его применении обновятся ресурсы, созданные вами в Console.

Запуск ant apply в CI

Без терминала ant apply выводит план и останавливается с сообщением cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan only. Настройте CI следующим образом:

• Запускайте ant apply --yes . в ветке по умолчанию после слияния, указывая каталог проекта. Команда ant apply --yes без аргументов синхронизирует только файлы, которые уже отслеживаются файлом блокировки, и пропускает новые.
• Для «pull request» (запросов на слияние) запускайте ant apply --dry-run ., чтобы показать план рецензентам. Этот запуск носит исключительно информационный характер и завершается с кодом 0, даже если план заблокирован.
• Фиксируйте обновленный claude-lock.json в конце задания, даже если шаг применения прервался с ошибкой: частичное применение все равно записывает созданные ресурсы.
• Не запускайте несколько применений одновременно: файл блокировки не защищен от параллельного доступа.
• Для аутентификации используйте Workload Identity Federation, а не сохраненный ключ API. Идентичность должна иметь доступ к организации и рабочему пространству, записанным в claude-lock.json. ant apply отклоняет учетные данные, относящиеся к любой другой организации или рабочему пространству.

Полный пример рабочего процесса GitHub Actions см. в разделе о CI в README CLI.

Флаги

Дальнейшие шаги