Lancer Claude Code depuis un script Python

Automatiser Claude Code depuis Python veut dire choisir une des deux portes que la documentation ouvre, pas inventer un client. La CLI non interactive est claude -p. Le paquet est claude-agent-sdk. Les deux pages relues le 18 octobre 2026 sont le quickstart de l'Agent SDK et la référence Python, plus la page « Run Claude Code programmatically » pour la CLI. Aucune commande de ce guide n'a été rejouée. Aucun script n'a donc « réparé » un fichier ici.

Le quickstart demande Python 3.10 ou plus récent, ou Node.js 18 ou plus récent si vous prenez la voie TypeScript, que ce texte ne suit pas. Un compte Anthropic est aussi listé. L'installation de la commande claude elle-même, si vous passez par la CLI, est dans Installer Claude Code.

Prérequis

Le quickstart dit que les SDK TypeScript et Python embarquent en général un binaire natif de Claude Code. Deux exceptions sont écrites sur la page. Si pip installe la distribution source du SDK Python au lieu d'une wheel, par exemple sur Windows ARM64, aucun binaire n'est livré : il faut alors une installation native de Claude Code, que le SDK cherche dans le PATH. Un npm ci --omit=optional concerne le SDK TypeScript, pas le venv Python ci-dessous.

La référence Python refuse un pip install direct sur le Python du système pour les installations récentes Debian, Ubuntu et Homebrew. L'erreur nommée est error: externally-managed-environment. D'où le venv, avant toute autre commande.

Installer le paquet dans un venv

Commandes de la référence Python, relues le 18 octobre 2026, non rejouées :

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

La page renvoie au quickstart pour uv, pour PowerShell, et pour la clé d'API. Ce guide ne recopie pas l'onglet PowerShell, qui n'était pas dans l'extrait relu. Sur macOS et Linux, le quickstart donne :

export ANTHROPIC_API_KEY=your-api-key

Remplacez your-api-key par une clé créée dans la Claude Console, à l'adresse que la page indique : platform.claude.com. Le SDK lit la variable dans l'environnement du processus qui lance l'agent. Il ne charge pas un fichier .env tout seul. Si la clé est dans un .env, le quickstart dit de la charger vous-même avant l'appel, par exemple avec le paquet dotenv.

La même page est nette sur un point que les tutoriels tiers sautent : sauf accord préalable, Anthropic n'autorise pas un développeur tiers à offrir la connexion claude.ai, ni les plafonds de cette connexion, dans un produit construit sur l'Agent SDK. L'authentification documentée ici est la clé d'API, ou les variables des fournisseurs listés sur la page (Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, Microsoft Foundry). Ce guide ne détaille pas ces quatre configurations. Elles ont leurs propres pages, que le quickstart cite.

Ce que le quickstart exécute, et ce qu'il ne faut pas copier tel quel

Le quickstart construit un agent qui lit utils.py, trouve des plantages, et modifie le fichier. Le script documenté importe query, ClaudeAgentOptions, AssistantMessage et ResultMessage. Il appelle query avec allowed_tools valant Read, Edit et Glob, et permission_mode valant acceptEdits. La page dit que ce mode approuve automatiquement les modifications de fichiers. Le lancement documenté, une fois le script enregistré sous agent.py, est :

python agent.py

La page décrit une fin Done: success et un utils.py modifié. Ce n'est pas une sortie observée ici. Ne lancez pas cet exemple dans un dépôt qui contient autre chose qu'un fichier d'essai. acceptEdits plus Edit, c'est le quickstart, pas un réglage prudent pour un premier branchement.

Le tableau « Tools » de la même page associe Read, Glob et Grep à une analyse en lecture seule. Une restriction de l'exemple, qui n'est pas un second exemple officiel et qui n'a pas été exécutée, consiste à ne passer que ces trois noms dans allowed_tools, et à ne pas fixer permission_mode. Ce guide ne prétend pas connaître le mode par défaut : la page renvoie aux permissions pour l'ordre d'évaluation, et cette page-là n'a pas été utilisée comme source de commandes. Enlever Edit retire l'outil que le quickstart utilise pour corriger. C'est le but, tant que vous n'avez pas décidé qu'un script peut écrire.

La référence Python distingue query() et ClaudeSDKClient. query() ouvre une session neuve à chaque appel, sauf continue_conversation=True ou resume. ClaudeSDKClient garde la même session et sait interrompre. Pour un script qui fait un seul passage, query() est la fonction que le quickstart montre. Les fragments nus async for de la référence ne tournent pas seuls : la page dit de les envelopper dans async def main() et d'appeler asyncio.run(main()), comme le quickstart.

L'autre porte : claude -p

Si vous avez déjà la commande claude, la page headless dit d'ajouter -p (ou --print) pour un passage non interactif. Exemple de la page, non rejoué :

claude -p "What does the auth module do?"

Et, pour limiter les outils approuvés d'avance, l'exemple d'ouverture de la page :

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

auth.py est un nom d'exemple. La page dit de le remplacer par un fichier de votre projet. Edit et Bash ne sont pas une lecture seule. Pour un appel qui ne doit pas modifier le dépôt, la page du mode bare montre :

claude --bare -p "Summarize README.md" --allowedTools "Read"

--bare saute la découverte des hooks, skills, commandes, sous-agents, plugins, serveurs MCP, mémoire automatique et CLAUDE.md. Sans ce drapeau, claude -p charge le même contexte qu'une session interactive, y compris ce qui est configuré dans le répertoire courant ou dans ~/.claude. La page précise qu'une session -p n'affiche pas de dialogue de confiance du dossier, ni de demande d'approbation par serveur. Un hook de projet peut donc partir. Pour un script qui doit donner le même résultat sur chaque machine, la page recommande --bare.

En mode bare, Claude Code ne lit pas les identifiants OAuth ni le trousseau. Pour l'API Anthropic, il faut ANTHROPIC_API_KEY, ou un apiKeyHelper dans le JSON passé à --settings. Le code de sortie est 0 en succès, autre chose si l'exécution échoue. Un drapeau invalide part sur stderr avant le départ. Un échec pendant l'exécution, comme une authentification manquante, est imprimé comme résultat sur stdout. Un script qui ne regarde que stdout peut prendre un message d'échec pour une réponse.

Erreur fréquente

Deux messages reviennent dans les pages relues, et ils ne se corrigent pas de la même façon.

error: externally-managed-environment arrive quand pip install vise le Python du système. La référence Python donne le venv ci-dessus, pas un sudo pip, et pas un contournement du type --break-system-packages, qui n'est pas sur la page.

Not logged in ou Invalid API key sont les exemples d'erreur d'authentification du quickstart. La variable doit être définie dans le shell qui lance le script. Un .env non chargé ne compte pas. Le SDK ne le lit pas pour vous.

Vérification

Après le venv, la référence ne donne pas une commande du type « importe et affiche la version ». Le contrôle qu'elle documente, c'est d'arriver au pip install sans l'erreur d'environnement géré, puis de lancer le script du quickstart seulement sur un fichier d'essai. Si vous ne voulez pas d'écriture, ne lancez pas l'exemple acceptEdits. Comparez plutôt votre import à celui de la page : from claude_agent_sdk import query, ClaudeAgentOptions. Une différence de nom de module est une invention, pas une variante.

Pour la CLI, claude -p avec --allowedTools "Read" et un prompt de résumé est le contrôle documenté le plus étroit parmi les exemples relus. Le code de sortie dit si l'appel a été accepté. Le texte produit n'est pas une preuve que le dépôt est sain. Ce guide n'en a pas.

Sources

Pages relues le 18 octobre 2026 :

Sources recontrôlées le 19 octobre 2026. Les exemples officiels qui écrivent dans un fichier sont cités pour dire ce qu'ils font, pas pour les relancer sur un dépôt réel. Pas de tarif, pas de capture, pas de mesure de durée.