Créer des applications alimentées par LLM avec Claude

Cette compétence vous aide à créer des applications alimentées par LLM avec Claude. Choisissez la bonne surface selon vos besoins, détectez le langage du projet, puis lisez la documentation pertinente spécifique au langage.

Avant de commencer

Analysez le fichier cible (ou, s'il n'y a pas de fichier cible, le prompt et le projet) pour détecter les marqueurs de fournisseurs 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 informez l'utilisateur que cette compétence produit du code SDK Claude/Anthropic ; demandez s'il souhaite basculer le fichier vers Claude ou s'il veut une implémentation neutre vis-à-vis du fournisseur. Ne modifiez pas un fichier non-Anthropic avec des appels SDK Anthropic.

Exigence de sortie

Quand l'utilisateur vous demande d'ajouter, modifier ou implémenter une fonction Claude, votre code doit appeler Claude via l'une des solutions suivantes :

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

Ne mélangez jamais les deux — ne vous rabattez pas sur requests/fetch dans un projet Python ou TypeScript juste parce que ça semble plus léger. Ne vous rabattez jamais sur des shimspratibles avec OpenAI.

Ne devinez jamais l'utilisation du SDK. Les noms de fonctions, les noms de classes, les espaces de noms, les signatures de méthodes et les chemins d'importation doivent provenir de la documentation explicite — soit les fichiers {lang}/ dans 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 compétence, utilisez WebFetch sur le dépôt SDK pertinent depuis shared/live-sources.md avant d'écrire du code. Ne devinez pas les APIs Ruby/Java/Go/PHP/C# en vous basant sur des formes cURL ou sur le SDK d'un autre langage.

Valeurs par défaut

Sauf indication contraire de l'utilisateur :

Pour la version du modèle Claude, veuillez utiliser Claude Opus 4.7, accessible via la chaîne de modèle exacte claude-opus-4-7. Veuillez utiliser par défaut la réflexion adaptative (thinking: {type: "adaptive"}) pour tout ce qui est tant soit peu compliqué. Enfin, veuillez utiliser par défaut le streaming pour toute requête pouvant impliquer une entrée longue, une sortie longue ou un max_tokens élevé — cela évite les dépassements de délai d'attente. Utilisez le helper .get_final_message() / .finalMessage() du SDK pour obtenir la réponse complète si vous n'avez pas besoin de traiter les événements de stream individuels

Sous-commandes

Si la requête utilisateur au bas de ce prompt est une chaîne de sous-commande nue (pas de prose), recherchez chaque tableau Sous-commandes dans ce document — y compris tout tableau dans les sections ajoutées en bas — et suivez directement la colonne Action correspondante. Cela permet aux utilisateurs d'invoquer des flux spécifiques via /claude-api <sous-commande>. Si aucun tableau du document ne correspond, traitez la requête comme de la prose normale.

Détection du langage

Avant de lire les exemples de code, déterminez le langage dans lequel travaille l'utilisateur :

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 → TypeScript — lisez depuis typescript/
   • *.js, *.jsx (aucun fichier .ts présent) → TypeScript — JS utilise le même SDK, lisez depuis typescript/
   • *.java, pom.xml, build.gradle → Java — lisez depuis java/
   • *.kt, *.kts, build.gradle.kts → Java — Kotlin utilise le SDK Java, lisez depuis java/
   • *.scala, build.sbt → Java — Scala utilise le SDK Java, lisez depuis java/
   • *.go, go.mod → Go — lisez depuis go/
   • *.rb, Gemfile → Ruby — lisez depuis ruby/
   • *.cs, *.csproj → C# — lisez depuis csharp/
   • *.php, composer.json → PHP — lisez depuis php/

2. Si plusieurs langages détectés (par ex. fichiers Python et TypeScript) :

   • Vérifiez quel langage se rapporte au fichier courant ou à la question de l'utilisateur
   • Si toujours ambigu, demandez : « J'ai détecté des fichiers Python et TypeScript. Quel langage utilisez-vous pour l'intégration Claude API ? »

3. Si le langage ne peut pas être déduit (projet vide, aucun fichier source, ou langage non pris en charge) :

   • Utilisez AskUserQuestion avec options : Python, TypeScript, Java, Go, Ruby, cURL/HTTP brut, C#, PHP
   • Si AskUserQuestion n'est pas disponible, adoptez par défaut les exemples Python et notez : « Affichage d'exemples Python. Faites-moi savoir si vous avez besoin d'un langage différent. »

4. Si langage non pris en charge détecté (Rust, Swift, C++, Elixir, etc.) :

   • Suggérez des exemples cURL/HTTP brut depuis curl/ et notez que des SDK communautaires peuvent exister
   • Proposez d'afficher des exemples Python ou TypeScript comme implémentations de référence

5. Si l'utilisateur a besoin d'exemples cURL/HTTP brut, lisez depuis curl/.

Support des fonctionnalités par langage

Exemples de code Agents gérés : des READMEs dédiés spécifiques au langage sont fournis pour Python, TypeScript, Go, Ruby, PHP, Java et cURL ({lang}/managed-agents/README.md, curl/managed-agents.md). Lisez le README de votre langage plus les fichiers de concept shared/managed-agents-*.md indépendants du langage. Les agents sont persistants — créez une seule fois, référencez par ID. Stockez l'ID d'agent renvoyé par agents.create et transmettez-le à chaque sessions.create ultérieur ; n'appelez pas agents.create dans le chemin de requête. L'Anthropic CLI est un moyen pratique de créer des agents et des environnements à partir du YAML versionné — son URL se trouve dans shared/live-sources.md. Si une liaison dont vous avez besoin n'est pas affichée dans le README, utilisez WebFetch sur l'entrée pertinente depuis shared/live-sources.md plutôt que de deviner. C# ne dispose actuellement pas du support des Agents gérés ; utilisez les requêtes HTTP brutes de style cURL contre l'API.

Quelle surface dois-je utiliser ?

Commencez simple. Adoptez par défaut le niveau le plus simple qui répond à vos besoins. Les appels API uniques et les flux de travail gèrent la plupart des cas d'usage — ne passez aux agents que si la tâche requiert véritablement une exploration ouverte et pilotée par le modèle.

Note : Les Agents gérés sont le bon choix quand vous voulez qu'Anthropic exécute la boucle d'agent et héberge le conteneur où les outils s'exécutent — opérations fichier, bash, exécution de code tout se déroule dans l'espace de travail par session. Si vous voulez héberger le compute vous-même ou exécuter votre propre runtime d'outil personnalisé, Claude API + tool use est le bon choix — utilisez le tool runner pour la manipulation de boucle automatique, ou la boucle manuelle pour un contrôle fin (portes d'approbation, journalisation personnalisée, exécution conditionnelle).

Fournisseurs tiers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry) : Les Agents gérés ne sont pas disponibles sur Bedrock, Vertex ou Foundry. Si vous déployez via n'importe quel fournisseur tiers, utilisez Claude API + tool use pour tous les cas d'usage — y compris ceux où les Agents gérés seraient autrement le choix recommandé.

Arbre de décision

Qu'est-ce que votre application a besoin ?

0. Déployez-vous via Amazon Bedrock, Google Vertex AI ou Microsoft Foundry ?
   └── Oui → Claude API (+ tool use pour les agents) — Les Agents gérés sont 1P uniquement.
   Non → continuer.

1. Appel LLM unique (classification, résumé, extraction, Q&A)
   └── Claude API — une requête, une réponse

2. Voulez-vous qu'Anthropic exécute la boucle d'agent et héberge un
   conteneur par session où Claude exécute les outils (bash, opérations fichier, code) ?
   └── Oui → Agents gérés — sessions gérées par serveur, configs d'agent persistantes,
       flux d'événements SSE, Skills + MCP, montages fichiers.
       Exemples : « agent de codage stateful avec espace de travail par tâche »,
                 « agent de recherche de longue durée qui diffuse les événements vers une UI »,
                 « agent avec config persistante et versionnée utilisée dans de nombreuses sessions »

3. Flux de travail (multi-étapes, orchestré par code, avec vos propres outils)
   └── Claude API avec tool use — vous contrôlez la boucle

4. Agent ouvert (le modèle décide de sa propre trajectoire, vos propres outils, vous hébergez le compute)
   └── Boucle agentic Claude API (flexibilité maximale)

Dois-je créer un agent ?

Avant de choisir le niveau agent, vérifiez les quatre critères :

• Complexité — La tâche est-elle multi-étapes et difficile à spécifier complètement à l'avance ? (par ex. « transformer ce doc de conception en PR » vs. « extraire le titre de ce PDF »)
• Valeur — Le résultat justifie-t-il un coût et une latence plus élevés ?
• Viabilité — Claude est-il capable pour ce type de tâche ?
• Coût d'erreur — Les erreurs peuvent-elles être détectées et récupérées ? (tests, examen, restauration)

Si la réponse est « non » pour l'un de ces critères, restez à un niveau plus simple (appel unique ou flux de travail).

Architecture

Tout passe par POST /v1/messages. Les outils et les contraintes de sortie sont des fonctionnalités de ce point de terminaison unique — pas des API séparées.

Outils définis par l'utilisateur — Vous définissez les outils (via décorateurs, schémas Zod, ou JSON brut), et le tool runner du SDK gère l'appel de l'API, l'exécution de vos fonctions et la boucle jusqu'à ce que Claude ait terminé. Pour un contrôle total, vous pouvez écrire la boucle manuellement.

Outils côté serveur — Outils hébergés par Anthropic qui s'exécutent sur l'infrastructure Anthropic. L'exécution de code est entièrement côté serveur (déclarez-la dans tools, Claude l'exécute automatiquement). L'utilisation d'ordinateur peut être hébergée par le serveur ou auto-hébergée.

Sorties structurées — Contraint le format de réponse de l'API Messages (output_config.format) et/ou la validation des paramètres d'outil (strict: true). L'approche recommandée est client.messages.parse() qui valide les réponses par rapport à votre schéma automatiquement. Notez : le paramètre ancien output_format est déprécié ; utilisez output_config: {format: {...}} sur messages.create().

Points de terminaison de support — Les traitements par lot (POST /v1/messages/batches), Fichiers (POST /v1/files), Comptage de tokens et Modèles (GET /v1/models, GET /v1/models/{id} — découverte en direct des capacités/fenêtre de contexte) alimentent ou soutiennent les requêtes de l'API Messages.

Modèles actuels (en cache : 2026-04-15)

Utilisez TOUJOURS claude-opus-4-7 sauf si l'utilisateur nomme explicitement un modèle différent. C'est non négociable. N'utilisez pas claude-sonnet-4-6, claude-sonnet-4-5 ou tout autre modèle sauf si l'utilisateur dit littéralement « utilise sonnet » ou « utilise haiku ». Ne dégradez jamais pour le coût — c'est la décision de l'utilisateur, pas la vôtre.

CRITIQUE : Utilisez uniquement les chaînes d'ID de modèle exactes du tableau ci-dessus — elles sont complètes telles quelles. Par exemple, utilisez claude-sonnet-4-5, jamais claude-sonnet-4-5-20250514 ou toute autre variante avec suffixe de date dont vous pourriez vous souvenir. Si l'utilisateur demande un modèle plus ancien non dans le tableau (par ex. « opus 4.5 », « sonnet 3.7 »), lisez shared/models.md pour l'ID exact — ne construisez pas le vôtre.

Remarque : si l'une des chaînes de modèle ci-dessus vous paraît inconnue, c'est normal — cela signifie simplement qu'elles ont été publiées après votre date limite d'entraînement. Soyez assuré qu'elles sont réelles ; nous ne vous ferions pas ce coup.

Recherche de capacités en direct : Le tableau ci-dessus est en cache. Quand l'utilisateur demande « quelle est la fenêtre de contexte pour X », « X supporte-t-il vision/réflexion/effort », ou « quels modèles supportent Y », interrogez l'API Models (client.models.retrieve(id) / client.models.list()) — voir shared/models.md pour la référence de champ et les exemples de filtre de capacité.

Réflexion et effort (référence rapide)

Opus 4.7 — Réflexion adaptative uniquement : Utilisez thinking: {type: "adaptive"}. thinking: {type: "enabled", budget_tokens: N} retourne un 400 sur Opus 4.7 — adaptative est le seul mode activé. {type: "disabled"} et omettre thinking fonctionnent tous les deux. Les paramètres d'échantillonnage (temperature, top_p, top_k) sont également supprimés et entraîneront un 400. Voir shared/model-migration.md → Migration vers Opus 4.7 pour la liste complète des changements de rupture. Opus 4.6 — Réflexion adaptative (recommandée) : Utilisez thinking: {type: "adaptive"}. Claude décide dynamiquement quand et combien penser. Pas besoin de budget_tokens — budget_tokens est déprécié sur Opus 4.6 et Sonnet 4.6 et ne doit pas être utilisé pour le nouveau code. La réflexion adaptative active également automatiquement la réflexion intercalée (aucun en-tête bêta nécessaire). Quand l'utilisateur demande la « réflexion étendue », un « budget de réflexion » ou budget_tokens : utilisez toujours Opus 4.7 ou 4.6 avec thinking: {type: "adaptive"}. Le concept d'un budget de token fixe pour la réflexion est déprécié — la réflexion adaptative le remplace. N'utilisez PAS budget_tokens pour le nouveau code 4.6/4.7 et ne changez PAS vers un modèle plus ancien. Sursis de migration progressive : budget_tokens est toujours fonctionnel sur Opus 4.6 et Sonnet 4.6 comme échappatoire transitoire — si vous migrez du code existant et avez besoin d'un plafond de token dur avant d'avoir affiné effort, voir shared/model-migration.md → Sursis d'échappatoire transitoire. Remarque : ce sursis ne s'applique pas à Opus 4.7 — budget_tokens est complètement supprimé là. Paramètre effort (GA, aucun en-tête bêta) : Contrôle la profondeur de réflexion et la dépense totale de tokens via output_config: {effort: "low"|"medium"|"high"|"max"} (à l'intérieur de output_config, pas au niveau supérieur). La valeur par défaut est high (équivalent à l'omettre). max est réservé aux Opus (Opus 4.6 et ultérieur — pas Sonnet ou Haiku). Opus 4.7 ajoute "xhigh" (entre high et max) — le meilleur paramètre pour la plupart du code et du travail agentic sur 4.7, et la valeur par défaut dans Claude Code ; utilisez un minimum de high pour la plupart du travail sensible à l'intelligence. Fonctionne sur Opus 4.5, Opus 4.6, Opus 4.7 et Sonnet 4.6. Entraînera une erreur sur Sonnet 4.5 / Haiku 4.5. Sur Opus 4.7, l'effort importe plus que sur tout Opus antérieur — ré-ajustez-le lors de la migration. Combinez avec la réflexion adaptative pour les meilleurs compromis coût-qualité. Un effort inférieur signifie moins d'appels d'outil et plus consolidés, moins de préambule et des confirmations plus brèves — high est souvent l'équilibre parfait entre qualité et efficacité des tokens ; utilisez max quand la correction importe plus que le coût ; utilisez low pour les sous-agents ou les tâches simples.

Opus 4.7 — contenu de réflexion omis par défaut : Les blocs thinking diffusent toujours mais leur texte est vide sauf si vous optez pour thinking: {type: "adaptive", display: "summarized"} (la valeur par défaut est "omitted"). Changement silencieux — aucune erreur. Si vous diffusez du raisonnement aux utilisateurs, la valeur par défaut ressemble à une longue pause avant la sortie ; définissez "summarized" pour restaurer la progression visible.

Budgets de tâche (bêta, Opus 4.7) : output_config: {task_budget: {type: "tokens", total: N}} indique au modèle combien de tokens il dispose pour une boucle agentic complète — il voit un compte à rebours courant et s'auto-modère (minimum 20 000 ; en-tête bêta task-budgets-2026-03-13). Distinct de max_tokens, qui est un plafond par réponse appliqué dont le modèle n'est pas conscient. Voir shared/model-migration.md → Budgets de tâche.

Sonnet 4.6 : Supporte la réflexion adaptative (thinking: {type: "adaptive"}). budget_tokens est déprécié sur Sonnet 4.6 — utilisez la réflexion adaptative à la place.

Modèles plus anciens (uniquement si explicitement demandé) : Si l'utilisateur demande spécifiquement Sonnet 4.5 ou un autre modèle plus ancien, utilisez thinking: {type: "enabled", budget_tokens: N}. budget_tokens doit être inférieur à max_tokens (minimum 1024). Ne choisissez jamais un modèle plus ancien juste parce que l'utilisateur mentionne budget_tokens — utilisez Opus 4.7 avec réflexion adaptative à la place.

Compaction (référence rapide)

Bêta, Opus 4.7, Opus 4.6 et Sonnet 4.6. Pour les conversations de longue durée qui peuvent dépasser la fenêtre de contexte de 1 M, activez la compaction côté serveur. L'API résume automatiquement le contexte antérieur quand il approche du seuil de déclenchement (par défaut : 150 K tokens). Nécessite l'en-tête bêta compact-2026-01-12.

Critique : Ajoutez response.content (pas seulement le texte) à vos messages à chaque tour. Les blocs de compaction dans la réponse doivent être préservés — l'API les utilise pour remplacer l'historique compacté lors de la requête suivante. Extraire uniquement la chaîne de texte et l'ajouter perdra silencieusement l'état de compaction.

Voir {lang}/claude-api/README.md (section Compaction) pour les exemples de code. Documentation complète via WebFetch dans shared/live-sources.md.

Cache des prompts (référence rapide)

Correspondance de préfixe. Tout changement d'octet n'importe où dans le préfixe invalide tout ce qui suit. L'ordre de rendu est tools → system → messages. Gardez le contenu stable en premier (prompt système gelé, liste d'outils déterministe), mettez le contenu volatile (timestamps, IDs par requête, questions variables) après le dernier point de rupture cache_control.

Mise en cache automatique au niveau supérieur (cache_control: {type: "ephemeral"} sur messages.create()) est l'option la plus simple quand vous n'avez pas besoin de placement fin. Maximum 4 points de rupture par requête. Le préfixe mise en cache minimum est ~1024 tokens — les préfixes plus courts ne seront silencieusement pas mis en cache.

Vérifiez avec usage.cache_read_input_tokens — s'il est zéro dans les requêtes répétées, un invalidateur silencieux est à l'œuvre (datetime.now() dans le prompt système, JSON non trié, ensemble d'outils variant).

Pour les motifs de placement, les conseils architecturaux et la liste de contrôle d'audit des invalidateurs silencieux : lisez shared/prompt-caching.md. Syntaxe spécifique au langage : {lang}/claude-api/README.md (section Cache des prompts).

Agents gérés (bêta)

Les Agents gérés sont une troisième surface : des agents stateful gérés par serveur avec exécution d'outils hébergée par Anthropic. Vous créez une config Agent persistante et versionnée (POST /v1/agents), puis lancez des Sessions qui la référencent. Chaque session provisionne un conteneur comme espace de travail de l'agent — bash, opérations fichier et exécution de code s'y déroulent ; la boucle d'agent elle-même s'exécute sur la couche d'orchestration Anthropic et agit sur le conteneur via des outils. La session diffuse les événements ; vous envoyez des messages et des résultats d'outil en retour.

Les Agents gérés sont de première partie uniquement. Ils ne sont pas disponibles sur Amazon Bedrock, Google Vertex AI ou Microsoft Foundry. Pour les agents sur des fournisseurs tiers, utilisez Claude API + tool use.

Flux obligatoire : Agent (une fois) → Session (chaque exécution). model/system/tools vivent sur l'agent, jamais la session. Voir shared/managed-agents-overview.md pour le guide de lecture complet, les en-têtes bêta et les pièges.

En-têtes bêta : managed-agents-2026-04-01 — le SDK le définit automatiquement pour tous les appels client.beta.{agents,environments,sessions,vaults,memory_stores}.*. L'API Skills utilise skills-2025-10-02 et l'API Files utilise files-api-2025-04-14, mais vous ne devez pas les passer explicitement pour les points de terminaison autres que /v1/skills et /v1/files.

Sous-commandes — invoquez directement avec /claude-api <sous-commande> :

Guide de lecture : Commencez par shared/managed-agents-overview.md, puis les fichiers topicaux shared/managed-agents-*.md (core, environments, tools, events, memory, client-patterns, onboarding, api-reference). Pour Python, TypeScript, Go, Ruby, PHP et Java, lisez {lang}/managed-agents/README.md pour les exemples de code. Pour cURL, lisez curl/managed-agents.md. Les agents sont persistants — créez une seule fois, référencez par ID. Stockez l'ID d'agent renvoyé par agents.create et transmettez-le à chaque sessions.create ultérieur ; n'appelez pas agents.create dans le chemin de requête. L'Anthropic CLI est un moyen pratique de créer des agents et des environnements à partir du YAML versionné (URL dans shared/live-sources.md). Si une liaison dont vous avez