claude-api

Construction d'applications basées sur LLM avec Claude

Cette compétence vous aide à construire des applications basées sur des grands modèles de langage (LLM) avec Claude. Choisissez la bonne surface selon vos besoins, détectez le langage du projet, puis lisez la documentation spécifique au langage correspondant.

Avant de commencer

Scannez le fichier cible (ou, s'il n'y a pas de fichier cible, l'invite et le projet) pour détecter des marqueurs de fournisseur non-Anthropic - import openai, from openai, langchain_openai, OpenAI(, gpt-4, gpt-5, des noms de fichiers comme agent-openai.py ou *-generic.py, ou toute instruction explicite de garder le code neutre vis-à-vis du fournisseur. Si vous en trouvez, arrêtez-vous et dites à l'utilisateur que cette compétence produit du code SDK Claude/Anthropic ; demandez-lui s'il veut basculer le fichier vers Claude ou s'il préfère une implémentation non-Claude. Ne modifiez pas un fichier non-Anthropic avec des appels au SDK Anthropic. (Exception : la sous-commande prompt-audit est non interactive et ne s'arrête pas ici - elle enregistre les marqueurs de fournisseur non-Anthropic dans les hypothèses déclarées de son rapport et ne propose jamais de basculer un fichier non-Anthropic vers le SDK Anthropic.)

Exigence de sortie

Lorsque l'utilisateur vous demande d'ajouter, de modifier ou d'implémenter une fonctionnalité Claude, votre code doit appeler Claude via l'un des moyens suivants :

1. Le SDK officiel Anthropic pour le langage du projet (anthropic, @anthropic-ai/sdk, com.anthropic.*, etc.). C'est le choix par défaut chaque fois qu'un SDK supporté existe pour le projet.
2. HTTP brut (curl, requests, fetch, httpx, etc.) - uniquement lorsque l'utilisateur demande explicitement cURL/REST/HTTP brut, que le projet est un projet shell/cURL, ou que le langage ne dispose pas de SDK officiel.

Ne mélangez jamais les deux - n'utilisez pas requests/fetch dans un projet Python ou TypeScript simplement parce que cela semble plus léger. Ne recourez jamais à des émulations compatibles OpenAI.

Ne devinez jamais l'utilisation du SDK. Les noms de fonctions, noms de classes, espaces de noms, signatures de méthodes et chemins d'importation doivent provenir d'une documentation explicite - soit les fichiers {lang}/ de cette compétence, soit les dépôts SDK officiels ou les liens de documentation listés dans shared/live-sources.md. Si la liaison dont vous avez besoin n'est pas explicitement documentée dans les fichiers de la compétence, récupérez le dépôt SDK pertinent depuis shared/live-sources.md via WebFetch avant d'écrire du code. N'inférez pas les API Ruby/Java/Go/PHP/C# à partir de formes cURL ou du SDK d'un autre langage.

Si WebFetch ou l'accès au dépôt échoue (réseau restreint, timeouts, clonage bloqué) : ne continuez pas à réessayer - écrivez le code à partir des motifs et des tables d'espaces de noms/paquets dans le fichier {lang}/, exécutez le compilateur ou l'interpréteur sur celui-ci, et itérez sur la sortie d'erreur. Pour les SDK typés statiquement (C#, Java, Go), une boucle de compilation-correction contre les erreurs locales permet d'atteindre un code fonctionnel plus rapidement qu'une recherche réseau bloquée.

Valeurs par défaut

Sauf demande contraire de l'utilisateur :

Pour la version du modèle Claude, veuillez utiliser Claude Opus 5.5, accessible via la chaîne de modèle exacte claude-opus-5-5. Par défaut, utilisez la pensée adaptative (thinking: {type: "adaptive"}) pour tout ce qui est un tant soit peu complexe. Et enfin, par défaut, utilisez le streaming pour toute requête pouvant impliquer une entrée longue, une sortie longue, ou un max_tokens élevé - cela évite les timeouts de requête. Utilisez l'assistant .get_final_message() / .finalMessage() du SDK pour obtenir la réponse complète si vous n'avez pas besoin de gérer les événements de flux individuels. Lorsqu'une requête en streaming définit des outils (client) définis par l'utilisateur, définissez eager_input_streaming: true sur chacun de ces outils afin que les entrées importantes des outils (contenus de fichiers, code, documents) soient diffusées au fur et à mesure de leur génération au lieu d'arriver en une seule rafale après que le serveur a fini de les mettre en mémoire tampon ; le client possède alors la validation : les analyseurs tolérants des SDK peuvent renvoyer une entrée silencieusement tronquée au lieu de lever une exception, validez donc chaque entrée d'outil analysée par rapport à son schéma avant de l'exécuter (les assistants d'exécution typés comme betaZodTool / @beta_tool typé le font ; les outils de schéma JSON betaTool() et les boucles manuelles doivent se valider eux-mêmes), traitez un échec comme un JSON invalide (INVALID_JSON erreur tool_result lorsque vous détenez le bloc, réémettez dans le cas contraire), vérifiez les raisons d'arrêt max_tokens / refusal avant d'exécuter les outils, et n'attrapez que l'erreur JSON du SDK, jamais ses erreurs d'API typées - motif dans shared/tool-use-concepts.md -> Diffusion rapide des entrées. Laissez-le désactivé pour les requêtes non streamées, pour les outils serveur, et lorsque la requête passe par un proxy ou un déploiement Bedrock plus ancien qui rejette le champ.

Avertissement : Dérive de l'API - Vos connaissances préalables peuvent être obsolètes

Plusieurs formes courantes de l'API Claude ont changé entre 2025 et 2026. Si vous vous souvenez d'un motif issu de votre formation, vérifiez-le par rapport aux fichiers {lang}/ de cette compétence avant d'écrire - les lignes ci-dessous sont les points de dérive les plus fréquents :

Domaine	Connaissance obsolète	API actuelle
Pensée étendue	thinking: {type: "enabled", budget_tokens: N}	Sur les modèles Claude 4.6+ : thinking: {type: "adaptive"}. budget_tokens est déprécié sur Opus 4.6 / Sonnet 4.6 et rejeté avec un 400 sur Fable 5/5.1 / Sonnet 5.5 / Sonnet 5 / Opus 5.5 / 5 / 4.8 / 4.7. Les modèles antérieurs à 4.6 utilisent encore budget_tokens.
Type d'outil de recherche web / récupération web	web_search_20250305, web_fetch_20250910	web_search_20260209, web_fetch_20260209 (filtrage dynamique) sur Opus 5.5/5/4.8/4.7/4.6, Sonnet 5.5, Sonnet 5, et Sonnet 4.6. Les modèles plus anciens conservent les variantes de base ; sur Vertex AI seule la variante de base web_search_20250305 est disponible (la récupération web n'est pas sur Vertex) - voir le QR des Outils Serveur ci-dessous.
Noms de paramètres PHP	noms d'arguments en snake_case (max_tokens)	Les arguments nommés de premier niveau sont en camelCase (maxTokens). Les clés des tableaux imbriqués varient selon la fonctionnalité (par ex. 'taskBudget', 'skillID', 'mcp_server_name') - copiez la clé exacte de l'exemple documenté ; ne faites pas de conversion en masse.
Identifiants des agents gérés	Gardez les secrets côté hôte via des outils personnalisés (la seule option avant le déploiement des coffres)	Identifiants environment_variable du coffre - stockés par Anthropic, substitués à la sortie, jamais visibles dans le bac à sable (shared/managed-agents-tools.md -> Coffres). Les outils personnalisés côté hôte restent la solution de repli pour les bacs à sable auto-hébergés.
API Fichiers / Compétences	client.beta.files.* / client.beta.skills.* avec l'en-tête beta files-api-2025-04-14 / skills-2025-10-02	Hors bêta : client.files.* / client.skills.*, pas d'en-tête beta. Dans les SDK actuels, client.beta.files / client.beta.skills ont des changements de forme cassants par rapport aux versions précédentes, correspondant aux espaces de noms stables - migrez selon shared/live-sources.md -> API Fichiers / Guide des Compétences.

Les fichiers {lang}/ de cette compétence font autorité sur les motifs mémorisés.

---

Sous-commandes

Si la demande de l'utilisateur en bas de cette invite est une chaîne de sous-commande nue (sans prose), recherchez chaque table Sous-commandes dans ce document - y compris dans les sections ajoutées ci-dessous - et suivez directement l'Action correspondante. Cela permet aux utilisateurs d'invoquer des flux spécifiques via /claude-api <sous-commande>. Si aucune table dans le document ne correspond, traitez la demande comme une prose normale.

Sous-commande	Action
migrate	Migrez le code API Claude existant vers un modèle plus récent. Lisez shared/model-migration.md immédiatement et suivez-le dans l'ordre : Étape 0 (confirmez la portée - demandez quels fichiers/répertoires avant toute modification), Étape 1 (classez chaque fichier), puis la section des changements cassants par cible. Ne résumez pas le guide - exécutez-le. Si l'utilisateur n'a pas nommé de modèle cible, demandez vers quel modèle migrer dans le même tour que la question de portée. Après l'application des modifications par cible, auditez le texte de l'invite, les descriptions d'outils et le code de requête dans la portée par rapport à shared/prompt-audit.md - les invites écrites pour le modèle source font partie de chaque migration, et cela ne s'annonce pas.
prompt-audit	Auditez les invites existantes, les descriptions d'outils, les compétences et les fichiers de configuration des agents (CLAUDE.md, fichiers de règles, commandes, sous-agents) pour détecter des motifs obsolètes ("cruft") : du texte écrit pour des modèles plus anciens, et des instructions que le dépôt a dépassées ou qui se contredisent. Lisez shared/prompt-audit.md immédiatement et suivez-le dans l'ordre : Étape 0 (établissez la portée et le modèle cible à partir de la demande et du dépôt - énoncez les hypothèses dans le rapport, ne vous arrêtez pas pour demander), inventaire, provenance, puis l'analyse des motifs. Produisez les deux livrables en entier - le rapport d'audit (constats avec fichier:ligne, motif, pourquoi il est obsolète, confiance) et un diff proposé - sans faire de pause pour confirmation ; n'appliquez les modifications que si la demande le demandait explicitement. Ne résumez pas le guide - exécutez-le.
upgrade	Mettez à niveau la dépendance du SDK Anthropic du projet à travers une version majeure - actuellement le SDK Python, anthropic 0.x -> 1.x. Les mots suivants peuvent nommer le langage et/ou une portée (upgrade python, upgrade python sdk src/). Lisez python/claude-api/sdk-upgrade.md immédiatement et suivez-le dans l'ordre : Étape 0 (confirmez la portée, puis établissez les versions actuelle et cible - une version 1.x publiée doit exister avant d'écrire un verrou), l'inventaire de l'Étape 1, chaque section numérotée, puis la vérification et le rapport. Ne résumez pas le guide - exécutez-le. Si le langage détecté ou nommé n'a pas de sdk-upgrade.md dans cette compétence, dites qu'aucun guide de mise à niveau de version majeure n'est fourni pour ce SDK et dirigez l'utilisateur vers le CHANGELOG de ce SDK (dépôts dans shared/live-sources.md) ; n'en improvisez pas un à partir du guide Python. Il ne s'agit pas d'une migration de modèle - pour déplacer du code vers un modèle Claude plus récent, utilisez migrate.
cost-optimize	Réduisez le coût d'exécution du code API Claude existant, sans sacrifier la qualité de sortie. Lisez shared/cost-optimization.md immédiatement et suivez-le dans l'ordre : Étape 0 (établissez la portée, le niveau de qualité et la référence), le profil de tokens - mesuré via l'API Admin Usage and Cost lorsque l'utilisateur a une clé API Admin, à partir des logs response.usage de l'application lorsqu'il les possède (demandez), ou estimé à partir du code autrement - puis une liste restreinte de leviers classés par économies (exprimée en dollars, % de la facture, ou en seaux relatifs selon la source de données que vous avez), des gains gratuits (mise en cache, hygiène des tokens d'entrée, hygiène des boucles, hygiène des tokens de sortie, batch) avant les compromis (budgets, effort, choix du modèle, multi-modèle) ; tout levier qui gagne une place devient son propre diff - proposé par défaut, appliqué et mesuré par rapport à l'évaluation couvrant le trafic qu'il touche lorsque l'utilisateur le demande et approuve - et "aucune modification recommandée" est un résultat valide. Deux règles permanentes : chaque exécution qui sollicite le modèle dépense de l'argent réel, donc obtenez d'abord l'approbation de l'utilisateur ; et lorsque le contexte pour un levier manque, travaillez de manière interactive avec l'utilisateur - ce workflow n'est pas censé faire l'audit en un seul essai. Ne résumez pas le guide - exécutez-le ; présenter le profil et le plan classé à l'utilisateur fait partie de son exécution.
build-eval	Aidez l'utilisateur à construire un jeu d'évaluation pour son application alimentée par Claude. Lisez shared/evals/build-eval.md immédiatement et lancez son entretien : Étape 0 (qu'est-ce qui est évalué), Étape 1 (sourcez les invites - évaluation existante / transcriptions / synthétisées), Étape 2 (méthode de notation), Étape 3 (script exécutable + coût mesuré). Obtenez l'accord explicite de l'utilisateur sur les entrées, la méthode de notation et le coût avant de produire l'évaluation.
preserved-thinking-migration	Rendez une intégration existante compatible avec la pensée préservée - la vérification qui maintient un bloc de pensée valide uniquement dans la conversation qui l'a produit. Lisez shared/preserved-thinking-migration.md immédiatement et suivez-le dans l'ordre : Étape 0 (portée, classes de trafic, plateforme et modèle, état de l'application, niveau de qualité, référence), Étape 0.5 (prouvez que la vérification s'exécute avec l'auto-test en trois requêtes), Étape 1 (capturez les corps de requête, différenciez les paires consécutives avec shared/preserved-thinking-migration/prefix_diff.py, scannez le code pour les causes, nommez chaque modification et dites si elle est délibérée), Étape 2 (rejouez une tranche de test avec prefix_mismatch_behavior: "drop_block" sous l'en-tête thinking-binding-controls-2026-08-01, comptez les nouveaux blocs supprimés par conversation, lisez l'en-tête de diagnostic lorsqu'il est présent), Étape 3 (une cause par diff dans l'ordre du raisonnement perdu - proposé par défaut, appliqué lorsque l'utilisateur le demande - puis remesurez, conservez ou revenez en arrière ; le protocole à trois bras lorsqu'une évaluation existe), la section de changement de modèle (dans shared/preserved-thinking-migration/causes.md, avec la table des causes et la liste de conservation) lorsque le harnais route entre les modèles, Étape 4 (le profil de rupture et les modifications). Deux règles permanentes : chaque rejeu dépense de l'argent réel, donc obtenez d'abord l'approbation de l'utilisateur pour le budget de mesure ; et "aucune modification recommandée" - la tranche a rejoué la pensée et rien n'a été supprimé - est un résultat valide. Les causes qui ont une forme uniquement additive sous une bêta plus récente (conservation de la queue et compactage en arrière-plan : compact-2026-09-04 ; modifications d'outils de même nom : inline-tools-2026-09-15) sont, lorsque cette bêta n'est pas disponible, mesurées et décidées, non réécrites. Pour le pourquoi (la vérification en trois étapes, la table des modifications additives) cela renvoie à shared/model-migration.md -> Changement cassant 3 ; ne résumez pas le guide - exécutez-le.
hillclimb	Améliorez de manière itérative l'application de l'utilisateur par rapport à une évaluation existante. Lisez shared/evals/eval-hillclimb.md immédiatement et suivez-le : Étape 0 (confirmez qu'une évaluation exécutable existe - sinon, orientez vers build-eval), Étape 1 (quoi modifier / ce qui est interdit), Étape 2 (budget + condition d'arrêt à partir du coût mesuré par exécution), obtenez l'approbation du plan, puis la boucle lire->proposer->appliquer->exécuter->enregistrer avec état sur disque et une division entraînement/validation/test.

---

Détection du langage

Avant de lire les exemples de code, déterminez dans quel langage l'utilisateur travaille (exception : pour la sous-commande prompt-audit, sautez les étapes de demande de cette section - l'audit est non interactif et son inventaire est indépendant du langage ; lorsqu'aucun langage n'est déductible, procédez sans demander et énoncez l'hypothèse dans le rapport) :

1. Examinez les fichiers du projet pour déduire le langage :

• *.py, requirements.txt, pyproject.toml, setup.py, Pipfile -> Python - lisez depuis python/
• *.ts, *.tsx, package.json, tsconfig.json, yarn.lock, pnpm-lock.yaml -> TypeScript - lisez depuis typescript/
• *.java, build.gradle, pom.xml, settings.gradle -> Java - lisez depuis java/
• *.go, go.mod, go.sum -> Go - lisez depuis go/
• *.rb, Gemfile, *.gemspec -> Ruby - lisez depuis ruby/
• *.php, composer.json -> PHP - lisez depuis php/
• *.cs, *.csproj, *.sln -> C# - lisez depuis csharp/
• *.swift, Package.swift -> Swift - lisez depuis swift/
• *.kt, build.gradle.kts -> Kotlin - lisez depuis kotlin/
• Cargo.toml -> Rust - lisez depuis rust/
• Makefile, *.sh ou aucune correspondance de projet -> Shell - lisez depuis shell/

2. Si aucun langage n'est évident (par exemple, pas de fichiers de configuration de projet), demandez poliment : "Pour quel langage de programmation dois-je écrire le code API Claude ? (Python, TypeScript, Java, Go, Ruby, PHP, C#, Swift, Kotlin, Rust, Shell, ou autre - précisez)"

3. Si l'utilisateur nomme un langage qui n'a pas de dossier dans cette compétence, dites "[Langage] n'est pas encore documenté dans cette compétence. Je vais récupérer le SDK officiel depuis les dépôts dans shared/live-sources.md et écrire le code à partir de ces sources."

---

Utiliser la compétence

Lisez la documentation spécifique au langage dans {lang}/ (python/, typescript/, java/, etc.) avant d'écrire du code. Les fichiers {lang}/ dans cette compétence décrivent :

• Configurer le SDK avec une clé API
• Initialiser le client
• Configurer la pensée étendue (adaptive, avec budget_tokens, ou désactivée)
• Appels en streaming vs non streamés
• Gestion des erreurs (exceptions de l'API, timeouts, erreurs de validation)
• Utiliser des outils
• Envoyer des images
• Utiliser des fichiers PDF
• Paramètres système, métadonnées utilisateur
• Appels batch
• Utiliser des compétences dans vos requêtes

Assurez-vous également de consulter shared/ pour des concepts transversaux :

Chemin	Contenu
shared/live-sources.md	Liens vers les dépôts SDK officiels et la documentation
shared/tool-use-concepts.md	Diffusion rapide des entrées, validation, boucles d'outils
shared/model-migration.md	Migration entre les modèles Claude
shared/prompt-audit.md	Audit des invites pour les motifs obsolètes
shared/cost-optimization.md	Réduction des coûts d'API
shared/preserved-thinking-migration.md	Rendre les intégrations compatibles avec la pensée préservée
shared/managed-agents-tools.md	Outils et configuration pour les agents gérés
shared/evals/	Construction et exécution d'évaluations (build-eval.md, eval-hillclimb.md)