Scripts et automatisation avec la CLI

Cette page couvre les flux de travail orientés tâches construits sur la CLI ant. Pour les options sous-jacentes et les options de sortie, consultez Utiliser la CLI.

Versionner les ressources de l'API

Vous pouvez utiliser la CLI pour versionner des ressources de l'API telles que des skills, des agents, des environnements ou des déploiements sous forme de fichiers YAML dans votre dépôt et les maintenir synchronisées avec l'API Claude.

1. 1

   Définir votre agent

   Écrivez la définition de l'agent dans 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. 2

   Créer l'agent

   ant beta:agents create < summarizer.agent.yaml

   

   Output

   

   {
     "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
     "version": 1,
     "name": "Summarizer",
     "model": "claude-opus-5"
     /* ... */
   }

   Notez l'id de la réponse. Vous le transmettrez à la commande de création de session lors d'une étape ultérieure.

3. 3

   Définir l'environnement

   Une session s'exécute dans un environnement, qui définit le bac à sable (sandbox) dans lequel elle s'exécute. Écrivez la définition de l'environnement dans summarizer.environment.yaml :

   summarizer.environment.yaml

   

   name: summarizer-env
   config:
     type: cloud
     networking:
       type: unrestricted

4. 4

   Créer l'environnement

   ant beta:environments create < summarizer.environment.yaml

   

   Output

   

   {
     "id": "env_01595EKxaaTTGwwY3kyXdtbs",
     "name": "summarizer-env"
     /* ... */
   }

   Notez l'id de la réponse. Vous le transmettrez à la commande de création de session lors d'une étape ultérieure.

5. 5

   Démarrer une session

   Collez l'id de l'agent et l'id de l'environnement issus des sorties précédentes dans la commande de création de session :

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

   

   Output

   

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

6. 6

   Envoyer un message utilisateur

   Copiez l'id de la session issu de la sortie précédente dans --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. 7

   Lire la conversation

   --transform s'applique à chaque événement listé, ce qui affiche donc le texte de chaque message dans l'ordre. --format auto remplace l'explorateur interactif que les commandes de liste ouvrent par défaut dans un 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.

Modèles de scripts

La CLI est conçue pour se combiner avec les outils shell standard.

Enchaîner la sortie d'une liste vers une seconde commande

--transform id --raw-output sur un point de terminaison de liste émet un ID brut par ligne, de sorte que les outils standard tels que head et xargs s'appliquent directement. Capturez le premier résultat, puis transmettez-le à une commande suivante :

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

Inspecter les erreurs

Les options --transform-error et --format-error appliquent le même filtrage aux réponses d'erreur. --raw-output ne s'applique pas aux erreurs ; utilisez donc --format-error yaml pour obtenir un scalaire sans guillemets. Extrayez uniquement le message d'erreur :

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

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

Utiliser la CLI depuis Claude Code

Claude Code peut utiliser la CLI ant sans configuration supplémentaire. Une fois la CLI installée et authentifiée, vous pouvez demander à Claude Code d'agir directement sur vos ressources de l'API. Par exemple :

• « Liste mes sessions d'agent récentes et résume celles qui ont échoué. »
• « Téléverse chaque PDF de ./reports vers l'API Files et affiche les ID obtenus. »
• « Récupère les événements de la session session_01... et dis-moi où l'agent s'est bloqué. »

Claude Code exécute ant dans le shell, analyse la sortie structurée et raisonne sur les résultats (aucun code d'intégration personnalisé n'est requis).

Authentifier les requêtes curl avec les identifiants de la CLI

Les scripts qui appellent l'API avec curl ou un autre client HTTP peuvent utiliser les identifiants stockés par ant auth login au lieu d'une clé API statique. Le jeton d'accès OAuth est placé dans l'en-tête Authorization en tant que jeton bearer ; l'en-tête x-api-key est réservé aux clés API statiques.

ant auth print-credentials --access-token affiche le jeton d'accès du profil actif, en le renouvelant d'abord s'il est expiré ou proche de l'expiration :

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

Exécutez ant auth status pour confirmer l'organisation et l'espace de travail auxquels vous êtes connecté ; la commande vous avertit lorsqu'une variable d'environnement remplace votre connexion.