Gerencie recursos como código com ant apply

ant apply cria e atualiza recursos da Claude API a partir de arquivos: agentes, ambientes, "skills" (habilidades), "memory stores" (armazenamentos de memória) e "deployments" (implantações). Esses arquivos ficam no seu repositório e passam pela mesma revisão que o seu código. Você descreve cada recurso em um arquivo, executa ant apply e aprova o plano exibido. Em seguida, você faz commit do claude-lock.json gerado, para que a próxima execução atualize os mesmos recursos em vez de criar novos.

Para instalar e autenticar a CLI, consulte o início rápido da CLI. ant apply requer a versão 1.30.0 ou posterior da CLI.

Aplique seu primeiro agente

Escreva o agente como um arquivo Markdown em agents/ e aplique-o:

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.

O "frontmatter" (bloco de metadados no início do arquivo) contém a configuração do agente (os campos de Defina seu agente) e o corpo é o seu prompt do sistema. ant apply infere que o arquivo é um agente a partir do seu caminho, neste caso o diretório agents/.

Em um terminal interativo, ant apply exibe o plano e aguarda sua aprovação:

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

Responda d para ver os detalhes primeiro: os campos de cada novo recurso, ou um diff campo a campo de cada atualização. --dry-run exibe esse plano detalhado e encerra sem alterar nada.

Para alterar o agente, edite o arquivo e execute ant apply novamente. O plano então mostra uma atualização em vez de uma criação.

Faça commit do claude-lock.json

O primeiro ant apply grava o claude-lock.json, o "lockfile" (arquivo de bloqueio), no diretório a partir do qual você o executa, portanto execute-o a partir da raiz do repositório. Ele registra o ID do recurso que cada arquivo criou e a organização e o workspace em que os recursos estão:

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

Faça commit dele junto com seus arquivos. É assim que a próxima execução, na sua máquina ou no CI, encontra esses recursos em vez de criá-los novamente, e é nele que você lê o ID de um agente para iniciar uma sessão. Os dois hashes identificam o que foi enviado por último e o que a API retornou. É assim que uma execução posterior percebe um arquivo editado, ou um recurso alterado fora desses arquivos.

Expanda para um projeto

Você também pode definir declarativamente os outros recursos como arquivos. Um arquivo contém o corpo da requisição que você enviaria ao endpoint de criação daquele tipo:

• Um ambiente é um arquivo YAML em environments/.
• Um armazenamento de memória é um arquivo YAML em memory_stores/.
• Uma implantação é um arquivo Markdown em deployments/: o frontmatter é o corpo da requisição e o texto se torna a mensagem que inicia cada sessão.
• Uma skill é um diretório com um SKILL.md na raiz, por convenção em skills/, enviado como um único pacote.

Qualquer recurso, exceto uma skill, pode ser escrito em YAML, JSON ou Markdown. Em Markdown, o frontmatter é o corpo e o texto preenche o campo de texto do tipo: o system de um agente, a description de um ambiente ou de um armazenamento de memória, a primeira mensagem de uma implantação.

Os recursos fazem referência uns aos outros por caminho. Onde quer que a API espere o ID de outro recurso, escreva o caminho relativo para o arquivo desse recurso. Neste projeto, o agente revisor lista ../skills/pr-summary em skills, o agente líder lista ./reviewer.md em sua equipe, e a implantação nomeia seu agente, ambiente e armazenamento de memória por caminho. ant apply os cria em ordem de dependência e preenche os IDs reais. O projeto tem seis arquivos:

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

Aplique o diretório inteiro:

ant apply .

O claude-lock.json passa então a ter uma entrada para cada arquivo do projeto.

Caminhos relativos são a forma como esses arquivos apontam uns para os outros. ant apply fixa as referências a agentes e skills na versão que acabou de aplicar, de modo que editar reviewer.md ou a skill atualiza tudo o que faz referência a eles na mesma execução. Um caminho também funciona dentro de um objeto, como na entrada resources da implantação, onde as outras chaves, como access, são mantidas.

Para apontar para um recurso que esses arquivos não gerenciam, escreva o ID dele (agent_..., skill_...). Qualquer outra coisa, como {type: anthropic, skill_id: xlsx}, é enviada à API como está escrita. Uma referência a skill também pode ser uma URL do GitHub no formato https://github.com/<owner>/<repo>/tree/<branch>/<dir>, por exemplo um diretório do repositório de skills de código aberto da Anthropic: ant apply baixa e envia esse diretório, fixado no commit resolvido até que você execute com --upgrade (defina GITHUB_TOKEN para um repositório privado).

Como o ant apply infere o tipo de um arquivo

Quando ant apply percorre um diretório, ele determina o tipo de cada arquivo pelo primeiro destes critérios que corresponder:

1. Um campo type de nível superior no arquivo.
2. O diretório em que o arquivo está diretamente: agents/, environments/, memory_stores/ ou deployments/.
3. Um nome de arquivo que começa com o tipo, como environment_staging.md.

Ele ignora arquivos que não correspondem a nenhum desses critérios, como READMEs e configurações de CI, a menos que você os nomeie na linha de comando. Um arquivo Markdown nomeado que não corresponde a nenhum é tratado como um agente, e um arquivo YAML ou JSON nomeado que não corresponde a nenhum gera um erro.

Edite e reaplique

Executar ant apply sem argumentos reconcilia todos os arquivos que o lockfile rastreia. Em um terminal, ele também lista os arquivos de recursos não rastreados no diretório do lockfile e oferece adicioná-los. Remover um campo de um arquivo limpa esse campo no recurso, se a API permitir que ele seja limpo. Um campo que você nunca definiu, ou que a API não consegue limpar, mantém seu valor atual.

Se um recurso foi editado, arquivado ou excluído fora desses arquivos (no Claude Console, por exemplo), o plano termina com This plan cannot be applied: e o motivo. O comando então encerra com refusing to apply. Passe --force para sobrescrever a edição ou criar um substituto.

Excluir um arquivo mantém seu recurso no lugar com um aviso, e --prune o remove (arquivando-o, ou excluindo-o no caso de uma skill). Renomear um arquivo, portanto, declara um novo recurso e mantém o antigo no lugar até que você faça o prune.

ant apply não consegue assumir um recurso que você criou no Console ou com ant beta:agents create. Apenas o que está no lockfile é gerenciado, e aplicar um arquivo que descreve um agente existente cria um segundo agente. Se você baixou seu agente do Console com Export as code, o download inclui seu próprio claude-lock.json, então aplicá-lo atualiza os recursos que você criou lá.

Execute o ant apply no CI

Sem um terminal, ant apply exibe o plano e para com cannot ask for confirmation without a terminal; re-run with --yes to apply, or --dry-run to see the plan only. Configure o CI da seguinte forma:

• Execute ant apply --yes . na sua branch padrão após o merge, nomeando o diretório do projeto. Um ant apply --yes sem argumentos reconcilia apenas os arquivos que o lockfile já rastreia e ignora um arquivo recém-adicionado.
• Em pull requests, execute ant apply --dry-run . para exibir o plano para os revisores. Ele é apenas informativo e encerra com 0 mesmo quando o plano está bloqueado.
• Faça commit do claude-lock.json atualizado ao final do job, mesmo quando a etapa de aplicação falhou no meio do caminho, porque uma aplicação parcial ainda registra o que criou.
• Execute uma aplicação por vez, porque nada bloqueia o lockfile.
• Autentique-se com Workload Identity Federation em vez de uma chave de API armazenada, como uma identidade que tenha acesso à organização e ao workspace registrados no claude-lock.json. ant apply recusa credenciais que correspondam a qualquer outra organização ou workspace.

Para um workflow completo do GitHub Actions, consulte o exemplo de CI no README da CLI.

Flags

Próximos passos