Claude Platform Docs

Scripting e automazione con la CLI

Gestisci il controllo di versione delle risorse API come file YAML, concatena i comandi della CLI ant negli script, opera sulle risorse da Claude Code e autentica le chiamate curl con le credenziali della CLI.

Questa pagina tratta i flussi di lavoro orientati alle attività basati sulla CLI ant. Per i flag sottostanti e le opzioni di output, consulta Usare la CLI.

Controllo di versione delle risorse API

Puoi usare la CLI per gestire il controllo di versione delle risorse API come skill, agenti, ambienti o deployment sotto forma di file YAML nel tuo repository e mantenerle sincronizzate con la Claude API.

  1. Definisci il tuo agente

    Scrivi la definizione dell'agente in 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. Crea l'agente

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

    Prendi nota dell'id nella risposta. Lo passerai al comando di creazione della sessione in un passaggio successivo.

  3. Definisci l'ambiente

    Una sessione viene eseguita in un ambiente, che definisce la sandbox in cui viene eseguita. Scrivi la definizione dell'ambiente in summarizer.environment.yaml:

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

  4. Crea l'ambiente

    ant beta:environments create < summarizer.environment.yaml
    Output
    {
  "id": "env_01595EKxaaTTGwwY3kyXdtbs",
  "name": "summarizer-env"
  /* ... */
}

    Prendi nota dell'id nella risposta. Lo passerai al comando di creazione della sessione in un passaggio successivo.

  5. Avvia una sessione

    Incolla l'id dell'agente e l'id dell'ambiente dagli output precedenti nel comando di creazione della sessione:

    ant beta:sessions create \
  --agent agent_011CYm1BLqPXpQRk5khsSXrs \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "Summarization task"
    Output
    {
  "id": "session_01JZCh78XvmxJjiXVy3oSi7K",
  "status": "running"
  /* ... */
}

  6. Invia un messaggio utente

    Copia l'id della sessione dall'output precedente in --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. Leggi la conversazione

    --transform viene eseguito su ogni evento elencato, quindi questo stampa il testo di ogni messaggio in ordine. --format auto sostituisce l'esploratore interattivo che i comandi di elenco aprono per impostazione predefinita in un terminale:

    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.

Pattern di scripting

La CLI è progettata per integrarsi con gli strumenti standard della shell.

Concatena l'output di un elenco in un secondo comando

--transform id --raw-output su un endpoint di elenco emette un ID semplice per riga, quindi strumenti standard come head e xargs si applicano direttamente. Cattura il primo risultato, quindi passalo a un comando successivo:

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

Ispeziona gli errori

I flag --transform-error e --format-error applicano lo stesso filtraggio alle risposte di errore. --raw-output non si applica agli errori, quindi usa --format-error yaml per ottenere uno scalare senza virgolette. Estrai solo il messaggio di errore:

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.

Usa la CLI da Claude Code

Claude Code può usare la CLI ant senza configurazione aggiuntiva. Con la CLI installata e autenticata, puoi chiedere a Claude Code di operare direttamente sulle tue risorse API. Ad esempio:

  • "Elenca le mie sessioni agente recenti e riassumi quali hanno generato errori."
  • "Carica ogni PDF in ./reports nella Files API e stampa gli ID risultanti."
  • "Recupera gli eventi della sessione session_01... e dimmi dove l'agente si è bloccato."

Claude Code invoca ant tramite la shell, analizza l'output strutturato e ragiona sui risultati (non è richiesto alcun codice di integrazione personalizzato).

Autentica le richieste curl con le credenziali della CLI

Gli script che chiamano l'API con curl o un altro client HTTP possono usare le credenziali memorizzate da ant auth login invece di una "API key" (chiave API) statica. Il token di accesso OAuth va nell'header Authorization come bearer token; l'header x-api-key è solo per le chiavi API statiche.

ant auth print-credentials --access-token stampa il token di accesso del profilo attivo, aggiornandolo prima se è scaduto o prossimo alla scadenza:

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

Esegui ant auth status per confermare a quale organizzazione e workspace hai effettuato l'accesso; ti avvisa quando una variabile d'ambiente sta sovrascrivendo il tuo login.

Was this page helpful?