Mode headless et Agent SDK

Faire tourner Claude automatiquement dans des scripts et des pipelines CI/CD

⏱ Estim. ~6 min

01 · Lire

Jusqu'ici tout ce que tu as fait avec Claude Code est interactif — tu tapes, Claude répond, tu approuves. Mais si tu voulais que Claude tourne automatiquement ? Dans un pipeline CI/CD qui review chaque pull request ? Un script qui fixe les erreurs de lint toutes les nuits ?

Le mode headless (claude -p) fait tourner Claude sans terminal interactif. Tu lui donnes un prompt, il fait son travail, il renvoie un résultat. Pas de frappe, pas de dialogue d'approbation — juste de l'entrée et de la sortie.

C'est comme ça que les équipes intègrent Claude dans leurs flows automatisés : code review bots, test fixers, générateurs de documentation, et plus encore.

💡 Imagine çaLe Claude interactif, c'est comme une conversation à ton bureau avec un collègue. Le Claude headless, c'est comme lui envoyer une tâche par email — tu envoies la demande, il bosse, tu récupères le résultat. Pas d'aller-retour.

Points clés

claude -p lance Claude en non-interactif (mode headless)
Parfait pour les scripts, les pipelines CI/CD, l'automatisation
Pas de dialogue d'approbation — spécifie les outils autorisés à l'avance
La sortie peut être en texte, en JSON ou en JSON streamé

02 · Exemple de code

Voici les patterns courants du mode headless. Le flag -p rend la commande non-interactive.

Usage headless de base

# Simple query
claude -p "Find all TODO comments in this project"

# With allowed tools (auto-approved, no prompts)
claude -p "Run tests and fix failures" \
  --allowedTools "Bash(npm test*),Read,Edit"

# Structured JSON output
claude -p "List all API endpoints" \
  --output-format json

Le flag -p (raccourci de « print ») lance Claude en non-interactif. --allowedTools pré-approuve des outils précis pour que Claude puisse bosser sans prompt de permission. --output-format json renvoie des données structurées plutôt que du texte brut — utile quand un autre programme doit parser le résultat.

03 · Exemple de code

Voici comment les équipes utilisent le mode headless dans un pipeline CI/CD — un code reviewer automatique qui tourne à chaque pull request.

GitHub Actions — code review automatique

# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Review PR
        run: |
          claude -p "Review the changes in this PR. \
            Focus on bugs, security, and performance." \
            --allowedTools "Read,Grep,Glob" \
            --output-format text

Cette GitHub Action lance Claude en mode headless à chaque pull request. Elle n'autorise que des outils read-only (Read, Grep, Glob), donc Claude peut analyser le code sans rien modifier. La review s'affiche dans les logs CI pour que l'équipe puisse la lire.

04 · Lire

Pour les automatisations plus complexes, Anthropic propose l'Agent SDK — des bibliothèques Python et TypeScript supportées par les outils Claude pour construire des agents en production.

L'Agent SDK te donne le contrôle programmatique sur tout : quels outils sont disponibles, comment traiter les résultats, la gestion des sessions (reprise de conversations), et même les connexions aux MCP servers. C'est ce qui supporte les intégrations Claude Code les plus complexes.

La CLI (claude -p) convient aux automatisations simples. L'Agent SDK est là quand tu veux un contrôle programmatique complet — gestion d'erreurs personnalisée, streaming des résultats, chaîner plusieurs appels Claude, ou construire un produit par-dessus les capacités de Claude.

Points clés

Agent SDK : bibliothèques Python et TypeScript pour les agents en production
Contrôle programmatique complet sur les outils, sessions et résultats
CLI (claude -p) : automatisations simples et scripts
Agent SDK : applications complexes et systèmes en production
Gestion de session : capture et reprise programmatiques de conversation

05 · Exemple de code

Voici un exemple simple d'Agent SDK en TypeScript qui trouve et fixe des bugs par programmation.

Agent SDK — bug fixer

import { query } from '@anthropic-ai/claude-agent-sdk';

for await (const msg of query({
  prompt: "Find and fix the failing test in auth.test.ts",
  options: {
    allowedTools: ["Read", "Edit", "Bash"],
  }
})) {
  if (msg.result) {
    console.log('Fix applied:', msg.result);
  }
}

L'Agent SDK te donne une interface en streaming — tu itères sur les messages pendant que Claude bosse. Le tableau allowedTools contrôle ce que Claude peut faire. Quand Claude termine, le message result contient un résumé de ce qui a été fait. C'est comme ça qu'on construit des agents automatisés qui peuvent lire, éditer et lancer des commandes.

06 · Quiz

Quel flag fait tourner Claude Code en non-interactif, sans terminal interactif ?

claude --headless
claude --auto
claude -p
claude --batch

07 · Compléter

Pour lancer Claude dans un pipeline CI/CD sans interaction utilisateur, utilise claude _____ "ton prompt".

08 · Associer

Associe chaque méthode d'automatisation à son meilleur usage.

(Cette section est interactive — active JavaScript pour l'utiliser.)

Autres leçons de ce chapitre

⚠ L'expérience interactive complète nécessite JavaScript. Active-le et recharge la page.

※ Ce site est un projet éducatif indépendant — pas un produit officiel d'Anthropic. Claude™ est une marque déposée d'Anthropic, PBC.