Claude Platform Docs

Scripts e automação com a CLI

Controle a versão de recursos da API como YAML, encadeie comandos da CLI ant em scripts, opere em recursos a partir do Claude Code e autentique chamadas curl com credenciais da CLI.

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

Controle de versão de recursos da API

Você pode usar a CLI para controlar a versão de recursos da API, como skills, agentes, ambientes ou implantações, como arquivos YAML no seu repositório e mantê-los sincronizados com a Claude API.

  1. Defina seu agente

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

    summarizer.agent.yaml
    name: Summarizer
model: claude-opus-5
system: |
  You are a helpful assistant that writes concise summaries.
tools:
  - type: agent_toolset_20260401

  2. Crie o agente

    ant beta:agents create < summarizer.agent.yaml
    Output
    {
  "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
  "version": 1,
  "name": "Summarizer",
  "model": "claude-opus-5"
  /* ... */
}

    Anote o id da resposta. Você o passará para o comando de criação de sessão em uma etapa posterior.

  3. Defina o ambiente

    Uma sessão é executada em um ambiente, que define a sandbox na qual ela é executada. Escreva a definição do ambiente em summarizer.environment.yaml:

    summarizer.environment.yaml
    name: summarizer-env
config:
  type: cloud
  networking:
    type: unrestricted

  4. Crie o ambiente

    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.

  5. Inicie uma sessão

    Cole o id do agente e o id do ambiente 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"
  /* ... */
}

  6. 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."}]}'

  7. Leia a conversa

    --transform é executado em cada evento listado, portanto 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.

Padrões de scripting

A CLI foi projetada para se compor com ferramentas de shell padrão.

Encadeie a saída de listagem em um segundo comando

--transform id --raw-output em um endpoint de listagem emite um ID simples por linha, de modo que 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

Inspecione erros

As flags --transform-error e --format-error aplicam a mesma filtragem às respostas de erro. --raw-output não se aplica a erros, portanto 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.

Use a CLI a partir do Claude Code

O Claude Code pode usar a CLI ant imediatamente. Com a CLI instalada e autenticada, você pode pedir ao Claude Code que opere diretamente nos seus recursos da API. Por exemplo:

  • "Liste minhas sessões de agente 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 agente travou."

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

Autentique requisições curl com credenciais da CLI

Scripts que chamam a API com curl ou outro cliente HTTP podem usar as credenciais armazenadas por ant auth login em vez de uma "API key" (chave de API) estática. O token de acesso OAuth vai no cabeçalho Authorization como um bearer token; o cabeçalho x-api-key é apenas para chaves de API estáticas.

ant auth print-credentials --access-token imprime o token de acesso do perfil ativo, atualizando-o primeiro se estiver expirado ou próximo de expirar:

cURL
curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "hi"}]
  }'

Execute ant auth status para confirmar em qual organização e workspace você está conectado; ele avisa quando uma variável de ambiente está substituindo seu login.

Was this page helpful?