CLI, SDKs e bibliotecasCLI ant

Scripting e automação com CLI

Versione recursos da API como YAML, encadeie comandos do ant CLI em scripts e opere sobre recursos a partir do Claude Code.

Esta página aborda fluxos de trabalho orientados a tarefas construídos sobre o CLI ant. Para as flags subjacentes e opções de saída, consulte Usando o CLI.

Versionando recursos da API

Você pode usar o CLI para versionar recursos da API, como skills, agents, environments ou deployments, como arquivos YAML no seu repositório e mantê-los sincronizados com a API do Claude.

Para mais informações sobre esses recursos, consulte Managed Agents.

Defina seu agent

Escreva a definição do agent em summarizer.agent.yaml:

summarizer.agent.yaml

name: Summarizer
model: claude-sonnet-4-6
system: |
  You are a helpful assistant that writes concise summaries.
tools:
  - type: agent_toolset_20260401

Crie o agent
ant beta:agents create < summarizer.agent.yaml
Output
{ "id": "agent_011CYm1BLqPXpQRk5khsSXrs", "version": 1, "name": "Summarizer", "model": "claude-sonnet-4-6" /* ... */ }
Anote o id da resposta. Você o passará para o comando de criação de sessão em uma etapa posterior.
Faça o commit de summarizer.agent.yaml no seu repositório e mantenha-o sincronizado com a API no seu pipeline de CI. O comando de atualização precisa do ID do agent e da versão atual como flags:
CLI
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
Defina o environment
Uma sessão é executada em um environment, que define o sandbox em que ela é executada. Escreva a definição do environment em summarizer.environment.yaml:
summarizer.environment.yaml
name: summarizer-env config: type: cloud networking: type: unrestricted
Crie o environment
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
Anote o id da resposta. Você o passará para o comando de criação de sessão em uma etapa posterior.
Faça o commit de summarizer.environment.yaml no seu repositório e mantenha-o sincronizado com a API no seu pipeline de CI. O comando de atualização precisa do ID do environment como flag:
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

Inicie uma sessão

Cole o id do agent e o id do environment das saídas anteriores no comando de criação de sessão:

ant beta:sessions create \
  --agent agent_011CYm1BLqPXpQRk5khsSXrs \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "Summarization task"

Output

{
  "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
  "status": "running"
  /* ... */
}

Envie uma mensagem de usuário

Copie o id da sessão da saída anterior para --session-id:

ant beta:sessions:events send \
  --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
  --event '{type: user.message, content: [{type: text, text: "Summarize the benefits of type safety in one sentence."}]}'

Leia a conversa
--transform é executado em cada evento listado, então isso imprime o texto de cada mensagem em ordem. --format auto substitui o explorador interativo que os comandos de listagem abrem por padrão em um terminal:
ant beta:sessions:events list \ --session-id session_01JZCh78XvmxJjiXVy3oSi7K \ --transform 'content.0.text' --format auto --raw-output
Output
```
Summarize the benefits of type safety in one sentence.
Type safety catches errors at compile time rather than runtime, reducing bugs, improving code clarity, enabling better tooling support, and making codebases easier to maintain and refactor with confidence.
```
Para acompanhar uma sessão enquanto ela é executada, use ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K. Os eventos são escritos no stdout à medida que chegam.

Padrões de scripting

O CLI foi projetado para se compor com ferramentas padrão de shell.

Encadear a saída de listagem em um segundo comando

--transform id --raw-output em um endpoint de listagem emite um ID puro por linha, então ferramentas padrão como head e xargs se aplicam diretamente. Capture o primeiro resultado e, em seguida, passe-o para um comando subsequente:

FIRST_AGENT=$(ant beta:agents list \
  --transform id --raw-output | head -1)

ant beta:agents:versions list \
  --agent-id "$FIRST_AGENT" \
  --transform "{version,created_at}" --format jsonl

Inspecionar erros

As flags --transform-error e --format-error aplicam a mesma filtragem às respostas de erro. --raw-output não se aplica a erros, então use --format-error yaml para obter um escalar sem aspas. Extraia apenas a mensagem de erro:

ant beta:agents retrieve --agent-id bogus \
  --transform-error error.message --format-error yaml 2>&1

Output

GET "https://api.anthropic.com/v1/agents/bogus?beta=true": 404 Not Found
Agent not found.

Usar o CLI a partir do Claude Code

O Claude Code pode usar o CLI ant imediatamente. Com o CLI instalado e autenticado, você pode pedir ao Claude Code para operar diretamente sobre seus recursos da API. Por exemplo:

"Liste minhas sessões de agent recentes e resuma quais delas apresentaram erro."
"Faça upload de todos os PDFs em ./reports para a Files API e imprima os IDs resultantes."
"Obtenha os eventos da sessão session_01... e me diga onde o agent travou."

O Claude Code executa o ant via shell, analisa a saída estruturada e raciocina sobre os resultados (nenhum código de integração personalizado é necessário).

Was this page helpful?

CLI, SDKs e bibliotecasCLI ant

Scripting e automação com CLI

Versione recursos da API como YAML, encadeie comandos do ant CLI em scripts e opere sobre recursos a partir do Claude Code.

Esta página aborda fluxos de trabalho orientados a tarefas construídos sobre o CLI ant. Para as flags subjacentes e opções de saída, consulte Usando o CLI.

Versionando recursos da API

Você pode usar o CLI para versionar recursos da API, como skills, agents, environments ou deployments, como arquivos YAML no seu repositório e mantê-los sincronizados com a API do Claude.

Para mais informações sobre esses recursos, consulte Managed Agents.

Defina seu agent

Escreva a definição do agent em summarizer.agent.yaml:

summarizer.agent.yaml

name: Summarizer
model: claude-sonnet-4-6
system: |
  You are a helpful assistant that writes concise summaries.
tools:
  - type: agent_toolset_20260401

Crie o agent
ant beta:agents create < summarizer.agent.yaml
Output
{ "id": "agent_011CYm1BLqPXpQRk5khsSXrs", "version": 1, "name": "Summarizer", "model": "claude-sonnet-4-6" /* ... */ }
Anote o id da resposta. Você o passará para o comando de criação de sessão em uma etapa posterior.
Faça o commit de summarizer.agent.yaml no seu repositório e mantenha-o sincronizado com a API no seu pipeline de CI. O comando de atualização precisa do ID do agent e da versão atual como flags:
CLI
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
Defina o environment
Uma sessão é executada em um environment, que define o sandbox em que ela é executada. Escreva a definição do environment em summarizer.environment.yaml:
summarizer.environment.yaml
name: summarizer-env config: type: cloud networking: type: unrestricted
Crie o environment
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
Anote o id da resposta. Você o passará para o comando de criação de sessão em uma etapa posterior.
Faça o commit de summarizer.environment.yaml no seu repositório e mantenha-o sincronizado com a API no seu pipeline de CI. O comando de atualização precisa do ID do environment como flag:
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

Inicie uma sessão

Cole o id do agent e o id do environment das saídas anteriores no comando de criação de sessão:

ant beta:sessions create \
  --agent agent_011CYm1BLqPXpQRk5khsSXrs \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "Summarization task"

Output

{
  "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
  "status": "running"
  /* ... */
}

Envie uma mensagem de usuário

Copie o id da sessão da saída anterior para --session-id:

ant beta:sessions:events send \
  --session-id session_01JZCh78XvmxJjiXVy3oSi7K \
  --event '{type: user.message, content: [{type: text, text: "Summarize the benefits of type safety in one sentence."}]}'

Leia a conversa
--transform é executado em cada evento listado, então isso imprime o texto de cada mensagem em ordem. --format auto substitui o explorador interativo que os comandos de listagem abrem por padrão em um terminal:
ant beta:sessions:events list \ --session-id session_01JZCh78XvmxJjiXVy3oSi7K \ --transform 'content.0.text' --format auto --raw-output
Output
```
Summarize the benefits of type safety in one sentence.
Type safety catches errors at compile time rather than runtime, reducing bugs, improving code clarity, enabling better tooling support, and making codebases easier to maintain and refactor with confidence.
```
Para acompanhar uma sessão enquanto ela é executada, use ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K. Os eventos são escritos no stdout à medida que chegam.

Padrões de scripting

O CLI foi projetado para se compor com ferramentas padrão de shell.

Encadear a saída de listagem em um segundo comando

FIRST_AGENT=$(ant beta:agents list \
  --transform id --raw-output | head -1)

ant beta:agents:versions list \
  --agent-id "$FIRST_AGENT" \
  --transform "{version,created_at}" --format jsonl

Inspecionar erros

ant beta:agents retrieve --agent-id bogus \
  --transform-error error.message --format-error yaml 2>&1

Output

GET "https://api.anthropic.com/v1/agents/bogus?beta=true": 404 Not Found
Agent not found.

Usar o CLI a partir do Claude Code

O Claude Code pode usar o CLI ant imediatamente. Com o CLI instalado e autenticado, você pode pedir ao Claude Code para operar diretamente sobre seus recursos da API. Por exemplo:

"Liste minhas sessões de agent recentes e resuma quais delas apresentaram erro."
"Faça upload de todos os PDFs em ./reports para a Files API e imprima os IDs resultantes."
"Obtenha os eventos da sessão session_01... e me diga onde o agent travou."

O Claude Code executa o ant via shell, analisa a saída estruturada e raciocina sobre os resultados (nenhum código de integração personalizado é necessário).

Was this page helpful?