Créer des applications propulsées par des LLM avec Claude
Cette compétence vous aide à créer des applications propulsées par des LLM avec Claude. Choisissez la surface adaptée à vos besoins, détectez le langage du projet, puis lisez la documentation spécifique au langage.
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 pour le SDK Claude/Anthropic ; demandez s'il souhaite 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.
Exigence de sortie
Lorsque l'utilisateur vous demande d'ajouter, modifier ou implémenter une fonctionnalité Claude, votre code doit appeler Claude via l'une des méthodes suivantes :
- Le SDK Anthropic officiel pour le langage du projet (
anthropic,@anthropic-ai/sdk,com.anthropic.*, etc.). C'est la valeur par défaut chaque fois qu'un SDK pris en charge existe pour le projet. - HTTP brut (
curl,requests,fetch,httpx, etc.) — uniquement si l'utilisateur demande explicitement cURL/REST/HTTP brut, que le projet est un projet shell/cURL, ou que le langage n'a 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 solutions de compatibilité 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, utilisez WebFetch sur le dépôt SDK pertinent depuis shared/live-sources.md 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, délais d'attente, clone bloqué) : ne réessayez pas continuellement — écrivez le code à partir des motifs et des tableaux d'espaces de noms/packages dans le fichier {lang}/, exécutez le compilateur ou l'interpréteur dessus, et itérez sur la sortie d'erreur. Pour les SDK typés statiquement (C#, Java, Go), une boucle compilation-correction sur les erreurs locales atteint 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, accessible via la chaîne de modèle exacte claude-opus-5. Veuillez utiliser par défaut la pensée adaptative (thinking: {type: "adaptive"}) pour tout ce qui est un peu compliqué. Et enfin, veuillez utiliser par défaut le streaming pour toute requête pouvant impliquer une entrée longue, une sortie longue, ou des max_tokens élevés — 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.
⚠️ Dérive de l'API — Votre entraînement antérieur peut être obsolète
Plusieurs formes courantes de l'API Claude ont changé en 2025-2026. Si vous vous souvenez d'un motif issu de l'entraînement, 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 | Ancien entraînement | 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 une 400 sur Fable 5 / Sonnet 5 / Opus 5 / 4.8 / 4.7. Les modèles pré-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/4.8/4.7/4.6, Sonnet 5 et Sonnet 4.6. Les modèles plus anciens conservent les variantes de base ; sur Vertex AI, seule la version de base web_search_20250305 est disponible (la récupération Web n'est pas sur Vertex) — voir la QR des outils serveur ci-dessous. |
| Noms de paramètres PHP | Noms fil de fer en snake_case comme arguments nommés (max_tokens) | Les arguments nommés de premier niveau sont en camelCase (maxTokens). Les clés de tableaux imbriqués varient selon la fonctionnalité (par exemple 'taskBudget', 'skillID', 'mcp_server_name') — copiez la clé exacte depuis l'exemple documenté ; ne faites pas de conversion en masse. |
| Credentials des agents gérés | Conserver les secrets côté hôte via des outils personnalisés (la seule option avant l'arrivée des coffres) | Credentials Vault environment_variable — stockés par Anthropic, substitués à la sortie, jamais visibles dans le bac à sable (shared/managed-agents-tools.md → Vaults). Les outils personnalisés côté hôte restent la solution de repli pour les bacs à sable auto-hébergés. |
Les fichiers {lang}/ de cette compétence font autorité sur les motifs mémorisés.
Sous-commandes
Si la demande utilisateur en bas de cette invite est une simple chaîne de sous-commande (sans prose), recherchez dans chaque tableau Sous-commandes de ce document — y compris dans les sections ajoutées ci-dessous — 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 demande comme une prose normale.
| Sous-commande | Action |
|---|---|
migrate | Migrer du 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 (confirmer la portée — demandez quels fichiers/répertoires avant toute modification), Étape 1 (classer 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 la portée. |
Détection du langage
Avant de lire des exemples de code, déterminez dans quel langage l'utilisateur travaille :
-
Examinez les fichiers du projet pour inférer le langage :
*.py,requirements.txt,pyproject.toml,setup.py,Pipfile→ Python — lisez depuispython/*.ts,*.tsx,package.json,tsconfig.json→ TypeScript — lisez depuistypescript/*.js,*.jsx(aucun fichier.tsprésent) → TypeScript — JS utilise le même SDK, lisez depuistypescript/*.java,pom.xml,build.gradle→ Java — lisez depuisjava/*.kt,*.kts,build.gradle.kts→ Java — Kotlin utilise le SDK Java, lisez depuisjava/*.scala,build.sbt→ Java — Scala utilise le SDK Java, lisez depuisjava/*.go,go.mod→ Go — lisez depuisgo/*.rb,Gemfile→ Ruby — lisez depuisruby/*.cs,*.csproj→ C# — lisez depuiscsharp/*.php,composer.json→ PHP — lisez depuisphp/
-
Si plusieurs langages sont détectés (par exemple, des fichiers Python et TypeScript) :
- Vérifiez à quel langage se rapporte le fichier ou la question actuelle de l'utilisateur
- Si c'est encore ambigu, demandez : "J'ai détecté à la fois des fichiers Python et TypeScript. Quel langage utilisez-vous pour l'intégration de l'API Claude ?"
-
Si le langage ne peut pas être déduit (projet vide, aucun fichier source, ou langage non pris en charge) :
- Utilisez AskUserQuestion avec les options : Python, TypeScript, Java, Go, Ruby, cURL/HTTP brut, C#, PHP
- Si AskUserQuestion n'est pas disponible, utilisez par défaut des exemples Python et notez : "Affichage d'exemples Python. Dites-moi si vous avez besoin d'un langage différent."
-
Si un langage non pris en charge est 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 de montrer des exemples Python ou TypeScript comme implémentations de référence
- Suggérez des exemples cURL/HTTP brut depuis
-
Si l'utilisateur a besoin d'exemples cURL/HTTP brut, lisez depuis
curl/.
Prise en charge des fonctionnalités par langage
Chaque langage SDK ci-dessus prend en charge à la fois le Tool Runner bêta et les Agents gérés (bêta) — Python (décorateur @beta_tool), TypeScript (betaZodTool + Zod), Java (classes annotées), Go (BetaToolRunner dans le package toolrunner), Ruby (BaseTool + tool_runner), C# (BetaToolRunner + schéma JSON brut), PHP (BetaRunnableTool + toolRunner()) ; les points d'entrée de code se trouvent dans la référence rapide des modèles d'utilisation d'outils ci-dessous. cURL est HTTP brut (pas de fonctionnalités SDK) et prend en charge les Agents gérés.
Exemples de code pour les Agents gérés : voir le guide de lecture dans la section
## Agents gérés (Bêta)ci-dessous.
Quelle surface utiliser ?
Commencez simplement. Utilisez par défaut le niveau le plus simple qui répond à vos besoins. Les appels API uniques et les workflows couvrent la plupart des cas d'utilisation — n'utilisez les agents que lorsque la tâche nécessite vraiment une exploration ouverte et pilotée par le modèle. "Le plus simple" signifie le moins de code que vous possédez : pour un agent hébergé, planifié ou avec mémoire, les Agents gérés sont généralement l'option la plus simple (pas de code de boucle, pas de fichiers d'état, pas de planificateur), même s'il s'agit d'une plateforme plus grande.
| Cas d'utilisation | Niveau | Surface recommandée | Pourquoi |
|---|---|---|---|
| Classification, résumé, extraction, Q&A | Appel LLM unique | API Claude | Une requête, une réponse |
| Traitement par lots ou embeddings | Appel LLM unique | API Claude | Points de terminaison spécialisés |
| Pipelines multi-étapes avec logique contrôlée par le code | Workflow | API Claude + utilisation d'outils | Vous orchestrez la boucle |
| Agent personnalisé avec vos propres outils | Agent | API Claude + utilisation d'outils | Flexibilité maximale |
| Agent avec état géré par le serveur et espace de travail | Agent | Agents gérés | Anthropic exécute la boucle et héberge le bac à sable d'exécution des outils |
| Configurations d'agent persistées et versionnées | Agent | Agents gérés | Les agents sont des objets stockés ; les sessions sont liées à une version |
| Agent multi-tours longue durée avec montages de fichiers | Agent | Agents gérés | Conteneurs par session, flux d'événements SSE, Compétences + MCP |
| Agent qui s'exécute selon un planning (cron, "chaque nuit") | Agent | Agents gérés — déploiements planifiés | Les déploiements déclenchent des sessions de manière autonome ; pas de planificateur côté client |
Note : Les agents gérés sont le bon choix lorsque vous souhaitez qu'Anthropic exécute la boucle de l'agent et héberge le conteneur où les outils s'exécutent — les opérations sur les fichiers, le bash, l'exécution de code s'exécutent tous dans l'espace de travail par session. Si vous souhaitez héberger vous-même le calcul ou exécuter votre propre environnement d'exécution d'outils personnalisé, l'API Claude + l'utilisation d'outils est le bon choix — utilisez le Tool Runner pour la boucle agentique — ses hooks par tour vous donnent toujours des portes d'approbation, de la journalisation, une interception d'erreurs et une exécution conditionnelle (voir
shared/tool-use-concepts.md) — ou la boucle manuelle lorsque vous souhaitez posséder l'ensemble de la boucle vous-même.
Accès via les fournisseurs cloud. Claude Platform on AWS est géré par Anthropic avec une parité API le jour même — voir
shared/claude-platform-on-aws.mdpour la configuration client. Pour la disponibilité par fonctionnalité sur Claude Platform on AWS, Amazon Bedrock, Google Vertex AI et Microsoft Foundry, voirshared/platform-availability.md— ce tableau est la source unique de vérité dans cette compétence ; n'inférez pas la disponibilité ailleurs.
Construire un agent : quatre approches
Une fois que vous avez décidé que vous avez réellement besoin d'un agent (utilisation d'outils ouverte et pilotée par le modèle), il existe quatre façons distinctes de le construire. Deux questions indépendantes les séparent : qui fournit le harnais (la boucle de l'agent + la gestion du contexte) et qui fournit le déploiement (l'infrastructure sur laquelle l'agent s'exécute). Le Tool Runner et le SDK Claude Agent fournissent tous deux uniquement un harnais — vous les hébergez et les déployez vous-même — c'est pourquoi ils sont faciles à confondre. Les Agents gérés (CMA) est la seule option qui fournit à la fois le harnais et le déploiement géré ; la boucle manuelle ne fournit ni l'un ni l'autre.
| # | Approche | Vous écrivez | Harnais & déploiement | Outils disponibles | Utilisation |
|---|---|---|---|---|---|
| 1 | API Claude — boucle manuelle | La boucle while stop_reason == "tool_use" vous-même | Vous construisez le harnais ; vous hébergez | Uniquement les outils que vous définissez | Vous voulez posséder la totalité de la boucle — pas de dépendance bêta, ou un flux de contrôle que les hooks par tour du Tool Runner ne prennent pas en charge |
| 2 | API Claude — Tool Runner (client.beta.messages.tool_runner + @beta_tool / betaZodTool) | Juste les fonctions d'outil | Le SDK fournit la boucle (harnais uniquement) ; vous hébergez | Uniquement les outils que vous définissez | Un agent avec outils personnalisés sans écrire la boucle à la main (la plupart des cas). Les hooks par tour vous donnent toujours des portes d'approbation, une interception d'erreurs, une modification des résultats (par exemple cache_control), des tentatives, du streaming et une compaction |
| 3 | Agents gérés (REST, bêta) | Configuration de l'agent + résultats de vos outils | Anthropic fournit le harnais et héberge un bac à sable par session (harnais + déploiement) | Bac à sable hébergé par Anthropic (bash, fichiers, exécution de code) + Compétences/MCP + vos outils | Vous voulez qu'Anthropic exécute la boucle et héberge l'espace de travail par session ; configurations persistées/versionnées ; sessions longue durée |
| 4 | SDK Claude Agent — produit séparé (claude-agent-sdk / @anthropic-ai/claude-agent-sdk) | Une invite + options | Le SDK fournit le harnais Claude Code + outils intégrés (harnais uniquement) ; vous hébergez | Outils intégrés Lecture/Écriture/Édition/Bash/Glob/Grep/WebSearch/WebFetch + MCP + sous-agents | Vous voulez un agent de codage/système de fichiers clé en main s'exécutant sur votre propre infrastructure |
La division harnais/déploiement est le modèle mental clé : les options 1, 2 et 4 vous laissent le déploiement ; seule l'option 3 (CMA) ajoute un déploiement géré. Les options 1 à 3 sont ce que cette compétence génère ; l'option 4 est une bibliothèque différente avec sa propre documentation — voir la désambiguïsation ci-dessous.
Tool Runner ≠ SDK Claude Agent. Ces noms se ressemblent mais sont des packages différents :
- Tool Runner fait partie du SDK standard de l'API Anthropic (
anthropic/@anthropic-ai/sdk), accessible viaclient.beta.messages.tool_runner. Il automatise la boucle de l'agent.