CLI, SDK e librerieCLI ant

Scripting e automazione con la CLI

Gestisci le risorse API sotto controllo di versione come YAML, concatena comandi della CLI ant negli script e opera sulle risorse da Claude Code.

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

Controllo di versione delle risorse API

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

Per maggiori informazioni su queste risorse, consulta Managed Agents.

Definisci il tuo agente

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

Crea l'agente
ant beta:agents create < summarizer.agent.yaml
Output
{ "id": "agent_011CYm1BLqPXpQRk5khsSXrs", "version": 1, "name": "Summarizer", "model": "claude-sonnet-4-6" /* ... */ }
Prendi nota dell'id dalla risposta. Lo passerai al comando di creazione della sessione in un passaggio successivo.
Aggiungi summarizer.agent.yaml al tuo repository e mantienilo sincronizzato con l'API nella tua pipeline CI. Il comando di aggiornamento richiede l'ID dell'agente e la versione corrente come flag:
CLI
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
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
Crea l'ambiente
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
Prendi nota dell'id dalla risposta. Lo passerai al comando di creazione della sessione in un passaggio successivo.
Aggiungi summarizer.environment.yaml al tuo repository e mantienilo sincronizzato con l'API nella tua pipeline CI. Il comando di aggiornamento richiede l'ID dell'ambiente come flag:
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

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"
  /* ... */
}

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

Leggi la conversazione
--transform viene eseguito su ogni evento elencato, quindi questo stampa il testo di ogni messaggio in ordine. --format auto sovrascrive l'esploratore interattivo che i comandi list 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.
```
Per osservare una sessione mentre è in esecuzione, usa ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K. Gli eventi vengono scritti su stdout man mano che arrivano.

Pattern di scripting

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

Concatenare l'output di list in un secondo comando

--transform id --raw-output su un endpoint list 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

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

Usare la CLI da Claude Code

Claude Code può usare la CLI ant senza configurazioni aggiuntive. 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 per la sessione session_01... e dimmi dove l'agente si è bloccato."

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

Was this page helpful?

CLI, SDK e librerieCLI ant

Scripting e automazione con la CLI

Gestisci le risorse API sotto controllo di versione come YAML, concatena comandi della CLI ant negli script e opera sulle risorse da Claude Code.

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

Controllo di versione delle risorse API

Per maggiori informazioni su queste risorse, consulta Managed Agents.

Definisci il tuo agente

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

Crea l'agente
ant beta:agents create < summarizer.agent.yaml
Output
{ "id": "agent_011CYm1BLqPXpQRk5khsSXrs", "version": 1, "name": "Summarizer", "model": "claude-sonnet-4-6" /* ... */ }
Prendi nota dell'id dalla risposta. Lo passerai al comando di creazione della sessione in un passaggio successivo.
Aggiungi summarizer.agent.yaml al tuo repository e mantienilo sincronizzato con l'API nella tua pipeline CI. Il comando di aggiornamento richiede l'ID dell'agente e la versione corrente come flag:
CLI
ant beta:agents update --agent-id agent_011CYm1BLqPXpQRk5khsSXrs --version 1 < summarizer.agent.yaml
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
Crea l'ambiente
ant beta:environments create < summarizer.environment.yaml
Output
{ "id": "env_01595EKxaaTTGwwY3kyXdtbs", "name": "summarizer-env" /* ... */ }
Prendi nota dell'id dalla risposta. Lo passerai al comando di creazione della sessione in un passaggio successivo.
Aggiungi summarizer.environment.yaml al tuo repository e mantienilo sincronizzato con l'API nella tua pipeline CI. Il comando di aggiornamento richiede l'ID dell'ambiente come flag:
CLI
ant beta:environments update --environment-id env_01595EKxaaTTGwwY3kyXdtbs < summarizer.environment.yaml

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"
  /* ... */
}

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

Leggi la conversazione
--transform viene eseguito su ogni evento elencato, quindi questo stampa il testo di ogni messaggio in ordine. --format auto sovrascrive l'esploratore interattivo che i comandi list 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.
```
Per osservare una sessione mentre è in esecuzione, usa ant beta:sessions:events stream --session-id session_01JZCh78XvmxJjiXVy3oSi7K. Gli eventi vengono scritti su stdout man mano che arrivano.

Pattern di scripting

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

Concatenare l'output di list in un secondo 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

Ispezionare gli errori

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.

Usare la CLI da Claude Code

Claude Code può usare la CLI ant senza configurazioni aggiuntive. 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 per la sessione session_01... e dimmi dove l'agente si è bloccato."

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

Was this page helpful?