---
title: Gerencie recursos como código com ant apply
url: https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/apply
description: Declare agentes, ambientes, skills, armazenamentos de memória, implantações e vaults como arquivos no seu repositório e mantenha os recursos da API sincronizados com eles usando 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), "deployments" (implantações) e vaults. Esses arquivos ficam no seu repositório e suas alterações passam pela mesma revisão que o seu código. Você descreve cada recurso em um arquivo, executa `ant apply` e aprova o plano que ele mostra. Em seguida, você faz commit do `claude-lock.json` que ele grava, 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](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/quickstart). `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:
```bash CLI
ant apply agents/summarizer.md
```
```markdown
---
name: Summarizer
model: claude-opus-5-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](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup)) e o corpo é o seu prompt do sistema. `ant apply` [infere](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/apply#kind-inference) 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:
```text Output wrap
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:
```json claude-lock.json
{
"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](https://platform.claude.com/docs/pt-BR/managed-agents/sessions). 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](https://platform.claude.com/docs/pt-BR/managed-agents/environments) é um arquivo YAML em `environments/`.
* Um [armazenamento de memória](https://platform.claude.com/docs/pt-BR/managed-agents/memory) é um arquivo YAML em `memory_stores/`.
* Uma [implantação](https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-deployments) é 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](https://platform.claude.com/docs/pt-BR/managed-agents/skills) é um diretório com um `SKILL.md` na raiz, por convenção em `skills/`, enviado como um único pacote.
* Um [vault](https://platform.claude.com/docs/pt-BR/managed-agents/vaults) é um arquivo YAML em `vaults/` cujos únicos campos são `display_name` e, opcionalmente, `metadata`. Arquivos de vault exigem a versão 1.34.0 ou posterior da CLI.
Qualquer recurso, exceto uma skill, pode ser escrito como YAML, JSON ou Markdown. Em Markdown, o frontmatter é o corpo e o texto em prosa 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. Um vault não tem campo de texto, então `ant apply` recusa um arquivo Markdown de vault que contenha prosa.
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:
```markdown
---
name: Code reviewer
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
skills:
- ../skills/pr-summary
---
You review pull requests for correctness, security, and readability.
```
```markdown
---
name: Engineering lead
model: claude-opus-5-5
multiagent:
type: coordinator
agents:
- ./reviewer.md
---
You coordinate engineering work. Delegate code review to the reviewer.
```
```markdown
---
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.
```
```yaml
# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: review-env
description: Cloud container with limited networking for review sessions.
config:
type: cloud
networking:
type: limited
allow_package_managers: true
```
```yaml
# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: Review notes
description: Recurring issues and house-style decisions the reviewer has recorded between runs.
```
```markdown
---
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:
```bash CLI
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///tree//`, por exemplo um diretório do [repositório de skills](https://github.com/anthropics/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/`, `deployments/` ou `vaults/`.
3. Um nome de arquivo que começa com o tipo, como `environment_staging.md`.
* Vaults são a exceção: `ant apply` não obtém o tipo de um nome como `vault_staging.yaml`, porque outras ferramentas nomeiam seus arquivos de segredos como `vault.yml`. Mantenha um arquivo de vault em `vaults/` ou atribua a ele `type: vault`.
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](https://platform.claude.com/docs/pt-BR/manage-claude/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](https://github.com/anthropics/anthropic-cli#in-ci).
## Flags
| Flag | Efeito |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dry-run` | Exibe o plano e encerra sem aplicar nem gravar o lockfile. Encerra com 0 mesmo quando o plano está bloqueado. |
| `--yes` | Aplica sem pedir confirmação. Obrigatório quando não há terminal. |
| `--force` | Aplica mesmo quando um recurso foi alterado, arquivado ou excluído fora desses arquivos. |
| `--prune` | Remove recursos que estão no lockfile, mas não estão mais declarados em um arquivo. |
| `--upgrade` | Resolve novamente as skills referenciadas por URL do GitHub, que de outra forma permanecem fixadas no commit registrado no lockfile. |
| `--lock-file ` | Usa este lockfile em vez de procurar a partir do diretório atual em direção aos diretórios superiores. Mantenha um para cada organização ou workspace: `ant apply` recusa um lockfile cuja organização ou workspace não corresponda às suas credenciais. |
| `--verbose`, `-v` | Mostra recursos inalterados e os valores completos dos campos no plano. |
## Próximos passos
Execute os agentes que você aplicou, a partir da CLI ou de um SDK
Campos de implantação, histórico de execuções e pausa
Padrões de scripts e uso a partir do Claude Code