ClaudeAPI

Source: Contenu adapté de anthropics/skills (MIT).

Cette compétence vous aide à créer des applications basées sur LLM avec Claude. Choisissez la bonne surface en fonction de vos besoins, détectez la langue du projet, puis lisez la documentation spécifique à la langue correspondante.

Avant de commencer

Analysez le fichier cible (ou, s'il n'y a pas de fichier cible, l'invite et le projet) à la recherche de marqueurs de fournisseur non anthropiques -import openai,from openai,langchain_openai,OpenAI(,gpt-4,gpt-5, de noms de fichiers tels queagent-openai.pyou*-generic.py, ou toute instruction explicite pour conserver le code neutre du fournisseur. Si vous en trouvez, arrêtez-vous et dites à l'utilisateur que cette compétence produit du code Claude/Anthropic SDK; demandez-leur s'ils souhaitent basculer le fichier vers Claude ou s'ils souhaitent 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, de modifier ou d'implémenter une fonctionnalité Claude, votre code doit appeler Claude via l'un des éléments suivants:

1. Le SDK Anthropic officiel pour la langue du projet (anthropic,@anthropic-ai/sdk,com.anthropic.*, etc.). Il s'agit de la valeur par défaut chaque fois qu'un SDK pris en charge 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 n'a pas de SDK officiel.

Ne mélangez jamais les deux - n'utilisez pasrequests/fetchdans un projet Python ou TypeScript simplement parce que cela semble plus léger. Ne vous contentez jamais de cales compatibles 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 d'une documentation explicite: soit les fichiers{lang}/de cette compétence, soit les référentiels SDK officiels ou les liens de documentation répertoriés dansshared/live-sources.md. Si la liaison dont vous avez besoin n'est pas explicitement documentée dans les fichiers de compétences, WebFetch le référentiel SDK approprié à partir deshared/live-sources.mdavant d'écrire le code. Ne déduisez pas les API Ruby/Java/Go/PHP/C# à partir de formes cURL ou du SDK d'un autre langage.

Valeurs par défaut

Sauf demande contraire de l'utilisateur:

Pour la version modèle Claude, veuillez utiliser Claude Opus 4.7, auquel vous pouvez accéder via la chaîne de modèle exacteclaude-opus-4-7. 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 demande pouvant impliquer une entrée longue, une sortie longue ou unmax_tokensélevé - cela évite d'atteindre les délais d'expiration des demandes. 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 des événements de flux individuels

Sous-commandes

Si la demande de l'utilisateur au 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 annexées ci-dessous - et suivez directement la colonne Action correspondante. Cela permet aux utilisateurs d'appeler des flux spécifiques via/claude-api <subcommand>. Si aucun tableau du document ne correspond, traitez la demande comme de la prose normale.

Détection de la langue

Avant de lire des exemples de code, déterminez dans quelle langue l'utilisateur travaille:

1. Regardez les fichiers du projet pour déduire la langue:

   • *.py,requirements.txt,pyproject.toml,setup.py,Pipfile-> Python - lecture à partir depython/
   • *.ts,*.tsx,package.json,tsconfig.json-> TypeScript - lecture à partir detypescript/
   • *.js,*.jsx(aucun fichier.tsprésent) -> TypeScript - JS utilise le même SDK, lu à partir detypescript/
   • *.java,pom.xml,build.gradle-> Java - lecture à partir dejava/
   • *.kt,*.kts,build.gradle.kts-> Java - Kotlin utilise le SDK Java, lu depuisjava/
   • *.scala,build.sbt-> Java - Scala utilise le SDK Java, lu à partir dejava/
   • *.go,go.mod-> Go - lecture à partir dego/
   • *.rb,Gemfile-> Ruby - lecture à partir deruby/
   • *.cs,*.csproj-> C# - lecture à partir decsharp/
   • *.php,composer.json-> PHP - lecture depuisphp/

2. Si plusieurs langues sont détectées (par exemple, des fichiers Python et TypeScript):

   • Vérifiez à quelle langue le fichier ou la question actuelle de l'utilisateur se rapporte
   • Si votre ambiguïté persiste, demandez: "J'ai détecté des fichiers Python et TypeScript. Quel langage utilisez-vous pour l'intégration de l'API Claude?"

3. Si la langue ne peut pas être déduite (projet vide, aucun fichier source ou langue non prise en charge):

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

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

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

5. Si l'utilisateur a besoin d'exemples HTTP cURL/raw, lisez depuiscurl/.

Prise en charge des fonctionnalités spécifiques à la langue

Quelle surface dois-je utiliser?

Arbre de décision

What does your application need?

0. Are you deploying through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry?
    Yes -> Claude API (+ tool use for agents) - Managed Agents is 1P only.
   No -> continue.

1. Single LLM call (classification, summarization, extraction, Q&A)
    Claude API - one request, one response

2. Do you want Anthropic to run the agent loop and host a per-session
   container where Claude executes tools (bash, file ops, code)?
    Yes -> Managed Agents - server-managed sessions, persisted agent configs,
       SSE event stream, Skills + MCP, file mounts.
       Examples: "stateful coding agent with a workspace per task",
                 "long-running research agent that streams events to a UI",
                 "agent with persisted, versioned config used across many sessions"

3. Workflow (multi-step, code-orchestrated, with your own tools)
    Claude API with tool use - you control the loop

4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute)
    Claude API agentic loop (maximum flexibility)

Dois-je créer un agent?

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

• Complexité – La tâche comporte-t-elle plusieurs étapes et est-elle difficile à spécifier entièrement à l'avance? (par exemple, « transformer ce document de conception en PR » plutôt que « 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 d'accomplir ce type de tâche?
• Coût de l'erreur – Les erreurs peuvent-elles être détectées et récupérées? (tests, révision, rollback)

Si la réponse est « non » à l’une de ces questions, restez à un niveau plus simple (appel unique ou flux de travail).

Architecture

Tout passe parPOST /v1/messages. Les outils et les contraintes de sortie sont des fonctionnalités de ce point de terminaison unique, et non des API distinctes.

Outils définis par l'utilisateur - Vous définissez des outils (via des décorateurs, des schémas Zod ou du JSON brut), et le programme d'exécution d'outils 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 d'Anthropic. L'exécution du code se fait entièrement côté serveur (déclarez-le danstools, Claude exécute le code automatiquement). L'utilisation de l'ordinateur peut être hébergée sur un 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 de l'outil (strict: true). L'approche recommandée estclient.messages.parse()qui valide automatiquement les réponses par rapport à votre schéma. Remarque: l'ancien paramètreoutput_formatest obsolète; utilisezoutput_config: {format: {...}}surmessages.create().

Points de terminaison pris en charge: les lots (POST /v1/messages/batches), les fichiers (POST /v1/files), le comptage de jetons et les modèles (GET /v1/models,GET /v1/models/{id}- capacité en direct/découverte par fenêtre contextuelle) alimentent ou prennent en charge les requêtes API Messages.

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

Utilisez TOUJOURSclaude-opus-4-7à moins que l'utilisateur ne nomme explicitement un modèle différent. Ceci n'est pas négociable. N'utilisez pasclaude-sonnet-4-6,claude-sonnet-4-5ou tout autre modèle à moins que l'utilisateur ne dise littéralement « utilisez le sonnet » ou « utilisez le haïku ». Ne rétrogradez jamais pour des raisons de 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. N'ajoutez pas de suffixes de date. Par exemple, utilisezclaude-sonnet-4-5, jamaisclaude-sonnet-4-5-20250514ou toute autre variante avec suffixe de date dont vous pourriez vous souvenir à partir des données d'entraînement. Si l'utilisateur demande un modèle plus ancien qui ne figure pas dans le tableau (par exemple, "opus 4.5", "sonnet 3.7"), lisezshared/models.mdpour connaître l'ID exact - n'en construisez pas vous-même.

Remarque: si l'une des chaînes de modèles ci-dessus ne vous semble pas familière, c'est normal: cela signifie simplement qu'elles ont été publiées après la date limite de vos données d'entraînement. Rassurez-vous, ce sont de vrais modèles; nous ne vous embêterions pas comme ça.

Recherche de fonctionnalités en direct: Le tableau ci-dessus est mis en cache. Lorsque l'utilisateur demande « quelle est la fenêtre contextuelle pour X », « X prend-il en charge la vision/la réflexion/l'effort » ou « quels modèles prennent en charge Y », interrogez l'API des modèles (client.models.retrieve(id)/client.models.list()) - voirshared/models.mdpour la référence de champ et les exemples de filtre de capacités.

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

Opus 4.7 - Pensée adaptative uniquement: Utilisezthinking: {type: "adaptive"}.thinking: {type: "enabled", budget_tokens: N}renvoie un 400 sur Opus 4.7 - adaptatif est le seul mode activé.{type: "disabled"}et l'omission dethinkingfonctionnent toutes deux. Les paramètres d'échantillonnage (temperature,top_p,top_k) sont également supprimés et seront 400. Voirshared/model-migration.md-> Migration vers Opus 4.7 pour la liste complète des modifications avec rupture. Opus 4.6 - Pensée adaptative (recommandé): Utilisezthinking: {type: "adaptive"}. Claude décide de manière dynamique quand et combien réfléchir. Aucunbudget_tokensn'est nécessaire -budget_tokensest obsolète sur Opus 4.6 et Sonnet 4.6 et ne doit pas être utilisé pour le nouveau code. La pensée adaptative permet également automatiquement une réflexion entrelacée (aucun en-tête bêta nécessaire). Lorsque l'utilisateur demande une « réflexion étendue », un « budget de réflexion », oubudget_tokens: utilisez toujours Opus 4.7 ou 4.6 avecthinking: {type: "adaptive"}. Le concept d’un budget symbolique fixe pour la réflexion est obsolète – la pensée adaptative le remplace. N'utilisez PASbudget_tokenspour le nouveau code 4.6/4.7 et ne passez PAS à un modèle plus ancien. Exclusion de migration progressive:budget_tokensest toujours fonctionnel sur Opus 4.6 et Sonnet 4.6 comme trappe de secours de transition - si vous migrez du code existant et avez besoin d'un plafond de jetons dur avant d'avoir régléeffort, voirshared/model-migration.md-> Trappe de secours de transition. Remarque: cette exclusion ne s'applique pas à l'Opus 4.7 -budget_tokensy est entièrement supprimé. Paramètre d'effort (GA, pas d'en-tête bêta): Contrôle la profondeur de réflexion et la dépense globale en jetons viaoutput_config: {effort: "low"|"medium"|"high"|"max"}(à l'intérieur duoutput_config, pas au niveau supérieur). La valeur par défaut esthigh(équivalent à l'omettre).maxest uniquement de niveau Opus (Opus 4.6 et versions ultérieures - pas Sonnet ou Haiku). Opus 4.7 ajoute"xhigh"(entrehighetmax) - le meilleur paramètre pour la plupart des cas d'utilisation de codage et d'agent sur 4.7, et la valeur par défaut dans Claude Code; utilisez au minimum unhighpour la plupart des travaux sensibles au renseignement. Fonctionne sur Opus 4.5, Opus 4.6, Opus 4.7 et Sonnet 4.6. Erreur sur Sonnet 4.5 / Haiku 4.5. Sur Opus 4.7, l'effort compte plus que sur n'importe quel Opus précédent - réajustez-le lors de la migration. Combinez-le avec une réflexion adaptative pour obtenir les meilleurs compromis coût-qualité. Un effort moindre signifie des appels d'outils moins nombreux et plus consolidés, moins de préambule et des confirmations plus concises -highest souvent le point idéal pour équilibrer la qualité et l'efficacité des jetons; utilisezmaxlorsque l’exactitude compte plus que le coût; utilisezlowpour les sous-agents ou les tâches simples.

Opus 4.7 - contenu de réflexion omis par défaut: Les blocsthinkingsont toujours diffusés mais leur texte est vide, sauf si vous vous inscrivez avecthinking: {type: "adaptive", display: "summarized"}(la valeur par défaut est"omitted"). Changement silencieux - aucune erreur. Si vous diffusez le 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âches (bêta, Opus 4.7):output_config: {task_budget: {type: "tokens", total: N}}indique au modèle le nombre de jetons dont il dispose pour une boucle agentique complète - il voit un compte à rebours en cours et s'auto-modère (minimum 20 000; en-tête bêtatask-budgets-2026-03-13). Distinct demax_tokens, qui est un plafond par réponse imposé dont le modèle n'a pas connaissance. Voirshared/model-migration.md-> Budgets de tâches.

Sonnet 4.6: Prend en charge la pensée adaptative (thinking: {type: "adaptive"}).budget_tokensest obsolète sur Sonnet 4.6 - utilisez plutôt la pensée adaptative.

Modèles plus anciens (uniquement si demandé explicitement): Si l'utilisateur demande spécifiquement Sonnet 4.5 ou un autre modèle plus ancien, utilisezthinking: {type: "enabled", budget_tokens: N}.budget_tokensdoit être inférieur àmax_tokens(minimum 1024). Ne choisissez jamais un modèle plus ancien simplement parce que l'utilisateur mentionnebudget_tokens- utilisez plutôt Opus 4.7 avec une pensée adaptative.

Compactage (référence rapide)

Bêta, Opus 4.7, Opus 4.6 et Sonnet 4.6. Pour les conversations de longue durée pouvant dépasser la fenêtre contextuelle de 1 M, activez le compactage côté serveur. L'API résume automatiquement le contexte antérieur lorsqu'elle approche du seuil de déclenchement (par défaut: 150 000 jetons). Nécessite l’en-tête bêtacompact-2026-01-12.

Critique: Ajoutezresponse.content(pas seulement le texte) à vos messages à chaque tour. Les blocs de compactage dans la réponse doivent être conservé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 qui perdra silencieusement l'état de compactage.

Voir{lang}/claude-api/README.md(section Compactage) pour des exemples de code. Documents complets via WebFetch dansshared/live-sources.md.

Mise en cache des invites (référence rapide)

Correspondance du préfixe. Tout changement d'octet n'importe où dans le préfixe invalide tout ce qui suit. L'ordre de rendu esttools->system->messages. Conservez d'abord le contenu stable (invite système gelée, liste d'outils déterministes), placez le contenu volatil (horodatages, identifiants par demande, questions variables) après le dernier point d'arrêtcache_control.

La mise en cache automatique de niveau supérieur (cache_control: {type: "ephemeral"}surmessages.create()) est l'option la plus simple lorsque vous n'avez pas besoin d'un placement précis. Max 4 points d'arrêt par requête. Le préfixe minimum pouvant être mis en cache est d'environ 1 024 jetons - les préfixes plus courts ne seront pas mis en cache silencieusement.

Vérifiez avecusage.cache_read_input_tokens - s'il est nul lors de requêtes répétées, un invalidateur silencieux est à l'œuvre (datetime.now()dans l'invite système, JSON non trié, ensemble d'outils variable).

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

Agents gérés (bêta)

Agents gérés est une troisième surface: des agents avec état gérés par le serveur avec exécution d'outils hébergés par Anthropic. Vous créez une configuration d'agent persistante et versionnée (POST /v1/agents), puis démarrez les sessions qui y font référence. Chaque session provisionne un conteneur comme espace de travail de l'agent - bash, opérations sur fichiers et exécution de code y sont exécutés; la boucle d'agent elle-même s'exécute sur la couche d'orchestration d'Anthropic et agit sur le conteneur via des outils. La session diffuse les événements; vous renvoyez des messages et des résultats d’outils.

Les agents gérés sont uniquement propriétaires. Ils ne sont pas disponibles sur Amazon Bedrock, Google Vertex AI ou Microsoft Foundry. Pour les agents sur des prestataires tiers, utilisez Claude API + utilisation de l'outil.

Flux obligatoire: Agent (une fois) -> Session (à chaque exécution).model/system/toolsen direct sur l'agent, jamais sur la session. Voirshared/managed-agents-overview.mdpour 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 définit cela automatiquement pour tous les appelsclient.beta.{agents,environments,sessions,vaults,memory_stores}.*. L'API Skills utiliseskills-2025-10-02et l'API Files utilisefiles-api-2025-04-14, mais vous n'avez pas besoin de les transmettre explicitement pour les points de terminaison autres que/v1/skillset/v1/files.

Sous-commandes - invoquez directement avec/claude-api <subcommand>:

Guide de lecture: Commencez parshared/managed-agents-overview.md, puis les fichiers d'actualitéshared/managed-agents-*.md(noyau, environnements, outils, événements, résultats, multiagent, webhooks, mémoire, modèles client, intégration, référence API). Pour Python, TypeScript, Go, Ruby, PHP et Java, lisez{lang}/managed-agents/README.mdpour des exemples de code. Pour cURL, lisezcurl/managed-agents.md. Les agents sont persistants - créer une fois, référencer par ID. Stockez l'ID d'agent renvoyé paragents.createet transmettez-le à chaquesessions.createsuivant; n'appelez pasagents.createdans le chemin de la requête. L'Anthropic CLI est un moyen pratique de créer des agents et des environnements à partir de YAML à version contrôlée (URL dansshared/live-sources.md). Si une liaison dont vous avez besoin n'est pas affichée dans le langage README, WebFetch l'entrée correspondante deshared/live-sources.mdplutôt que de deviner. C# ne prend actuellement pas en charge les agents gérés; utilisez le HTTP brut decurl/managed-agents.mdcomme référence.

Lorsque l'utilisateur souhaite configurer un agent géré à partir de zéro (par exemple, "comment commencer", "guidez-moi pour en créer un", "configurer un nouvel agent"): lisezshared/managed-agents-onboarding.mdet exécutez son entretien - même flux que la sous-commandemanaged-agents-onboard.

Lorsque l'utilisateur demande "comment écrire le code client pour X": atteindreshared/managed-agents-client-patterns.md- couvre la reconnexion du flux sans perte, la porte mise en file d'attente/traitéeprocessed_at, l'interruption, l'aller-retourtool_confirmation, la porte de rupture inactive/terminée correcte, la course au statut post-inactivité, la commande du flux en premier, les pièges du montage de fichiers, la conservation des informations d'identification côté hôte via des outils personnalisés, etc.

Guide de lecture

Après avoir détecté la langue, lisez les fichiers pertinents en fonction des besoins de l'utilisateur:

Référence des tâches rapides

Classification/résumé/extraction/Q&R d'un seul texte: -> Lecture seule{lang}/claude-api/README.md

Interface utilisateur de chat ou affichage des réponses en temps réel: -> Lire{lang}/claude-api/README.md+{lang}/claude-api/streaming.md

Conversations de longue durée (peut dépasser la fenêtre contextuelle): -> Lire{lang}/claude-api/README.md- voir section Compactage Migration vers un modèle plus récent (Opus 4.7 / Opus 4.6 / Sonnet 4.6) ou remplacement d'un modèle retiré: -> Lireshared/model-migration.md Mise en cache rapide / optimisation de la mise en cache / "pourquoi mon taux de réussite dans le cache est-il faible": -> Lireshared/prompt-caching.md+{lang}/claude-api/README.md(section Mise en cache des invites)

Appel de fonction / utilisation d'outils / agents: -> Lire{lang}/claude-api/README.md+shared/tool-use-concepts.md+{lang}/claude-api/tool-use.md

Conception de l'agent (surface d'outils, gestion du contexte, stratégie de mise en cache): -> Lireshared/agent-design.md

Traitement par lots (non sensible à la latence): -> Lire{lang}/claude-api/README.md+{lang}/claude-api/batches.md

Importations de fichiers sur plusieurs requêtes: -> Lire{lang}/claude-api/README.md+{lang}/claude-api/files-api.md

Agents gérés (agents avec état gérés par le serveur avec espace de travail): -> Lireshared/managed-agents-overview.md+ le reste des fichiersshared/managed-agents-*.md. Pour Python, TypeScript, Go, Ruby, PHP et Java, lisez{lang}/managed-agents/README.mdpour des exemples de code. Pour cURL, lisezcurl/managed-agents.md. Les agents sont persistants - créer une fois, référencer par ID. Stockez l'ID d'agent renvoyé paragents.createet transmettez-le à chaquesessions.createsuivant; n'appelez pasagents.createdans le chemin de la requête. L'Anthropic CLI est un moyen pratique de créer des agents et des environnements à partir de YAML à version contrôlée (URL dansshared/live-sources.md). Si une liaison dont vous avez besoin n'est pas affichée dans le langage README, WebFetch l'entrée correspondante deshared/live-sources.mdplutôt que de deviner. C# ne prend actuellement pas en charge les agents gérés: utilisez le HTTP brut decurl/managed-agents.mdcomme référence.

API Claude (référence complète du fichier)

Lisez le dossier API Claude spécifique au langage ({language}/claude-api/):

1. {language}/claude-api/README.md - Lisez ceci en premier. Installation, démarrage rapide, modèles courants, gestion des erreurs.
2. shared/tool-use-concepts.md - Lire lorsque l'utilisateur a besoin d'un appel de fonction, d'une exécution de code, de mémoire ou de sorties structurées. Couvre les fondements conceptuels.
3. shared/agent-design.md - À lire lors de la conception d'un agent: bash ou outils dédiés, appels d'outils de programmation, recherche/compétences d'outils, édition de contexte, compactage ou mémoire, principes de mise en cache.
4. {language}/claude-api/tool-use.md - Lisez des exemples de code d'utilisation d'outils spécifiques au langage (exécuteur d'outils, boucle manuelle, exécution de code, mémoire, sorties structurées).
5. {language}/claude-api/streaming.md: à lire lors de la création d'interfaces utilisateur ou d'interfaces de chat qui affichent les réponses de manière incrémentielle.
6. {language}/claude-api/batches.md - Lire lors du traitement de nombreuses requêtes hors ligne (non sensible à la latence). Fonctionne de manière asynchrone à un coût de 50 %.
7. {language}/claude-api/files-api.md - Lire lors de l'envoi du même fichier sur plusieurs requêtes sans retélécharger.
8. shared/prompt-caching.md - À lire lors de l'ajout ou de l'optimisation de la mise en cache des invites. Couvre la conception de stabilité des préfixes, le placement des points d'arrêt et les anti-modèles qui invalident silencieusement le cache.
9. shared/error-codes.md - À lire lors du débogage des erreurs HTTP ou de la mise en œuvre de la gestion des erreurs.
10. shared/model-migration.md - À lire lors de la mise à niveau vers des modèles plus récents, du remplacement de modèles retirés ou de la traduction des modèlesbudget_tokens/pré-remplissage vers l'API actuelle.
11. shared/live-sources.md - URL WebFetch pour récupérer la dernière documentation officielle.

Quand utiliser WebFetch

Utilisez WebFetch pour obtenir la dernière documentation lorsque:

• L'utilisateur demande des informations « dernières » ou « actuelles »
• Les données mises en cache semblent incorrectes
• L'utilisateur pose des questions sur les fonctionnalités non couvertes ici

Les URL de la documentation en direct sont au formatshared/live-sources.md.

Pièges courants

• Ne tronquez pas les entrées lorsque vous transmettez des fichiers ou du contenu à l'API. Si le contenu est trop long pour tenir dans la fenêtre contextuelle, informez-en l'utilisateur et discutez des options (blocage, résumé, etc.) plutôt que de le tronquer silencieusement.
• Pensée Opus 4.7: Adaptatif uniquement.thinking: {type: "enabled", budget_tokens: N}renvoie 400 sur Opus 4.7 -budget_tokensy est entièrement supprimé (avectemperature,top_p,top_k). Utilisezthinking: {type: "adaptive"}.
• Opus 4.6 / Sonnet 4.6: Utilisezthinking: {type: "adaptive"}- n'utilisez PASbudget_tokenspour le nouveau code 4.6 (obsolète sur Opus 4.6 et Sonnet 4.6; pour une migration progressive du code existant, voir la trappe d'évacuation de transition dansshared/model-migration.md- notez que cette exclusion ne s'applique pas à l'Opus 4.7). Pour les modèles plus anciens,budget_tokensdoit être inférieur àmax_tokens(minimum 1024). Cela générera une erreur si vous vous trompez.
• Pré-remplissage de la famille 4.6/4.7 supprimé: Les pré-remplissages des messages de l'assistant (pré-remplissages du dernier tour de l'assistant) renvoient une erreur 400 sur Opus 4.6, Opus 4.7 et Sonnet 4.6. Utilisez plutôt des sorties structurées (output_config.format) ou des instructions d'invite système pour contrôler le format de réponse.
• Confirmez la portée de la migration avant de modifier: Lorsqu'un utilisateur demande de migrer le code vers un modèle Claude plus récent sans nommer un fichier, un répertoire ou une liste de fichiers spécifique, demandez quelle portée appliquer en premier: l'intégralité du répertoire de travail, un sous-répertoire spécifique ou un ensemble spécifique de fichiers. Ne commencez pas l’édition tant que l’utilisateur n’a pas confirmé. Les expressions impératives telles que "migrer ma base de code", "déplacer mon projet vers X", "mettre à niveau vers Sonnet 4.6" ou simplement "migrer vers Opus 4.7" sont encore ambiguës - elles vous disent quoi faire mais pas où, alors demandez. Continuez sans demander uniquement lorsque l'invite nomme un fichier exact, un répertoire spécifique ou une liste de fichiers explicite ("migrerapp.py", "migrer tout sousservices/", "mettre à joura.pyetb.py"). Voirshared/model-migration.mdétape 0.
• ** Valeurs par défaut demax_tokens: ** Ne minimisez pasmax_tokens- le fait d'appuyer sur le plafond tronque la sortie en cours de réflexion et nécessite une nouvelle tentative. Pour les requêtes sans streaming, la valeur par défaut est~16000(conserve les réponses dans les délais d'attente HTTP du SDK). Pour les demandes de streaming, la valeur par défaut est~64000(les délais d'attente ne sont pas un problème, alors donnez de la place au modèle). Ne descendez plus bas que lorsque vous avez une raison sérieuse: classification (~256), plafonds de coûts ou productions délibérément courtes.
• 128 000 jetons de sortie: Opus 4.6 et Opus 4.7 prennent en charge jusqu'à 128 000max_tokens, mais les SDK nécessitent le streaming pour des valeurs aussi grandes afin d'éviter les délais d'attente HTTP. Utilisez.stream()avec.get_final_message()/.finalMessage().
• Analyse JSON des appels d'outils (famille 4.6/4.7): Opus 4.6, Opus 4.7 et Sonnet 4.6 peuvent produire différentes chaînes JSON s'échappant dans les champsinputdes appels d'outils (par exemple, Unicode ou échappement par barre oblique). Analysez toujours les entrées de l'outil avecjson.loads()/JSON.parse()- ne faites jamais de correspondance de chaîne brute sur l'entrée sérialisée.
• Sorties structurées (tous les modèles): Utilisezoutput_config: {format: {...}}au lieu du paramètre obsolèteoutput_formatsurmessages.create(). Il s'agit d'un changement général de l'API, et non spécifique à la version 4.6.
• Ne réimplémentez pas la fonctionnalité du SDK: Le SDK fournit des aides de haut niveau: utilisez-les au lieu de créer à partir de zéro. Plus précisément: utilisezstream.finalMessage()au lieu d'encapsuler les événements.on()dansnew Promise(); utilisez des classes d'exceptions typées (Anthropic.RateLimitError, etc.) au lieu de messages d'erreur correspondant à des chaînes; utilisez les types de SDK (Anthropic.MessageParam,Anthropic.Tool,Anthropic.Message, etc.) au lieu de redéfinir des interfaces équivalentes.
• Ne définissez pas de types personnalisés pour les structures de données du SDK: Le SDK exporte les types pour tous les objets API. UtilisezAnthropic.MessageParampour les messages,Anthropic.Toolpour les définitions d'outils,Anthropic.ToolUseBlock/Anthropic.ToolResultBlockParampour les résultats d'outils,Anthropic.Messagepour les réponses. Définir votre propreinterface ChatMessage { role: string; content: unknown }duplique ce que le SDK fournit déjà et perd la sécurité des types.
• Sortie de rapports et de documents: Pour les tâches qui produisent des rapports, des documents ou des visualisations, le bac à sable d'exécution de code contientpython-docx,python-pptx,matplotlib,pillowetpypdfpréinstallés. Claude peut générer des fichiers formatés (DOCX, PDF, graphiques) et les renvoyer via l'API Files - considérez cela pour les demandes de type "rapport" ou "document" au lieu du texte brut de la sortie standard.

Fichiers de ressources

LICENCE.txt

Télécharger LICENSE.txt

Ressource binaire

csharp/claude-api.md

Télécharger csharp/claude-api.md

Ressource binaire

curl/exemples.md

Télécharger curl/examples.md

Ressource binaire

curl/managed-agents.md

Télécharger curl/managed-agents.md

Ressource binaire

aller/claude-api.md

Télécharger go/claude-api.md

Ressource binaire

aller/managed-agents/README.md

Télécharger go/managed-agents/README.md

Ressource binaire

java/claude-api.md

Télécharger java/claude-api.md

Ressource binaire

java/managed-agents/README.md

Télécharger java/managed-agents/README.md

Ressource binaire

php/claude-api.md

Télécharger php/claude-api.md

Ressource binaire

php/managed-agents/README.md

Télécharger php/managed-agents/README.md

Ressource binaire

python/claude-api/README.md

Télécharger python/claude-api/README.md

Ressource binaire

python/claude-api/batches.md

Télécharger python/claude-api/batches.md

# Message Batches API — Python

The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.

## Key Facts

- Up to 100,000 requests or 256 MB per batch
- Most batches complete within 1 hour; maximum 24 hours
- Results available for 29 days after creation
- 50% cost reduction on all token usage
- All Messages API features supported (vision, tools, caching, etc.)

---

## Create a Batch

```python
importation anthropique
à partir de anthropic.types.message_create_params import MessageCreateParamsNonStreaming
à partir de la demande d'importation anthropic.types.messages.batch_create_params

client = anthropique.Anthropique()

message_batch = client.messages.batches.create(
    requêtes=[
        Demande (
            custom_id="requête-1",
            params=MessageCreateParamsNonStreaming(
                modèle="claude-opus-4-7",
                max_tokens = 16 000,
                messages=[{"role": "user", "content": "Résumer les impacts du changement climatique"}]
            )
        ),
        Demande (
            custom_id="requête-2",
            params=MessageCreateParamsNonStreaming(
                modèle="claude-opus-4-7",
                max_tokens = 16 000,
                messages=[{"role": "user", "content": "Expliquer les bases de l'informatique quantique"}]
            )
        ),
    ]
)

print(f"ID du lot: {message_batch.id}")
print(f"Statut: {message_batch.processing_status}")

Poll for Completion

heure d'importation

tandis que Vrai:
    batch = client.messages.batches.retrieve(message_batch.id)
    si batch.processing_status == "terminé":
        pause
    print(f"Statut: {batch.processing_status}, traitement: {batch.request_counts.processing}")
    temps.sommeil(60)

print("Lot terminé!")
print(f"Réussite: {batch.request_counts.succeeded}")
print(f"Erreur: {batch.request_counts.errored}")

Retrieve Results

pour le résultat dans client.messages.batches.results(message_batch.id):
    correspondre à result.result.type:
        cas "réussi":
            msg = résultat.result.message
            text = next((b.text pour b dans msg.content si b.type == "text"), "")
            print(f"[{result.custom_id}] {texte[:100]}")
        cas "erré":
            si result.result.error.type == "invalid_request":
                print(f"[{result.custom_id}] Erreur de validation - corriger la demande et réessayer")
            sinon:
                print(f"[{result.custom_id}] Erreur de serveur - réessayez en toute sécurité")
        cas "annulé":
            print(f"[{result.custom_id}] Annulé")
        cas "expiré":
            print(f"[{result.custom_id}] Expiré - soumettre à nouveau")

Cancel a Batch

annulé = client.messages.batches.cancel(message_batch.id)
print(f"Statut: {cancelled.processing_status}") # "annulation"

Batch with Prompt Caching

système_partagé = [
    {"type": "text", "text": "Vous êtes un analyste littéraire."},
    {
        "type": "texte",
        "text": large_document_text, # Partagé entre toutes les requêtes
        "cache_control": {"type": "éphémère"}
    }
]

message_batch = client.messages.batches.create(
    requêtes=[
        Demande (
            custom_id=f"analyse-{i}",
            params=MessageCreateParamsNonStreaming(
                modèle="claude-opus-4-7",
                max_tokens = 16 000,
                système = système_partagé,
                messages=[{"role": "user", "content": question}]
            )
        )
        pour moi, question dans énumérer (questions)
    ]
)

Full End-to-End Example

importation anthropique
heure d'importation
à partir de anthropic.types.message_create_params import MessageCreateParamsNonStreaming
à partir de la demande d'importation anthropic.types.messages.batch_create_params

client = anthropique.Anthropique()

# 1. Préparer les demandes
items_to_classify = [
    "La qualité du produit est excellente!",
    "Service client épouvantable, plus jamais.",
    "C'est bon, rien de spécial.",
]

demandes = [
    Demande (
        custom_id=f"classify-{i}",
        params=MessageCreateParamsNonStreaming(
            modèle="claude-haïku-4-5",
            max_tokens = 50,
            messages=[{
                "rôle": "utilisateur",
                "content": f"Classer comme positif/négatif/neutre (un mot): {text}"
            }]
        )
    )
    pour moi, texte dans enumerate (items_to_classify)
]

# 2. Créer un lot
batch = client.messages.batches.create(requests=requests)
print(f"Lot créé: {batch.id}")

# 3. Attendez la fin
tandis que Vrai:
    batch = client.messages.batches.retrieve(batch.id)
    si batch.processing_status == "terminé":
        pause
    temps.sommeil(10)

# 4. Collectez les résultats
résultats = {}
pour le résultat dans client.messages.batches.results(batch.id):
    si result.result.type == "réussi":
        msg = résultat.result.message
        results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "")

pour custom_id, classement en sorted(results.items()):
    imprimer(f"{custom_id}: {classification}")

### python/claude-api/files-api.md

[Télécharger python/claude-api/files-api.md](/skills/claude-api/python/claude-api/files-api.md)

```markdown
# Files API — Python

The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.

**Beta:** Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).

## Key Facts

- Maximum file size: 500 MB
- Total storage: 100 GB per organization
- Files persist until deleted
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
- Not available on Amazon Bedrock or Google Vertex AI

---

## Upload a File

```python
importation anthropique

client = anthropique.Anthropique()

téléchargé = client.beta.files.upload(
    file=("rapport.pdf", open("rapport.pdf", "rb"), "application/pdf"),
)
print(f"ID de fichier: {uploaded.id}")
print(f"Taille: {uploaded.size_bytes} octets")

Use a File in Messages

PDF / Text Document

réponse = client.beta.messages.create(
    modèle="claude-opus-4-7",
    max_tokens = 16 000,
    messages=[{
        "rôle": "utilisateur",
        "contenu": [
            {"type": "text", "text": "Résumer les principales conclusions de ce rapport."},
            {
                "type": "document",
                "source": {"type": "file", "file_id": uploaded.id},
                "title": "Rapport Q4", # facultatif
                "citations": {"enabled": True} # facultatif, active les citations
            }
        ]
    }],
    bêtas=["files-api-2025-04-14"],
)
pour le bloc dans réponse.content:
    si block.type == "texte":
        imprimer (bloc.texte)

Image

fichier_image = client.beta.files.upload(
    file=("photo.png", open("photo.png", "rb"), "image/png"),
)

réponse = client.beta.messages.create(
    modèle="claude-opus-4-7",
    max_tokens = 16 000,
    messages=[{
        "rôle": "utilisateur",
        "contenu": [
            {"type": "text", "text": "Qu'y a-t-il dans cette image?"},
            {
                "type": "image",
                "source": {"type": "file", "file_id": image_file.id}
            }
        ]
    }],
    bêtas=["files-api-2025-04-14"],
)

Manage Files

List Files

fichiers = client.beta.files.list()
pour f dans files.data:
    print(f"{f.id}: {f.filename} ({f.size_bytes} octets)")

Get File Metadata

file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")
print(f"Nom du fichier: {file_info.filename}")
print(f"Type MIME: {file_info.mime_type}")

Delete a File

client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")

Download a File

Only files created by the code execution tool or skills can be downloaded (not user-uploaded files).

file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")
file_content.write_to_file("output.txt")

Full End-to-End Example

Upload a document once, ask multiple questions about it:

importation anthropique

client = anthropique.Anthropique()

# 1. Téléchargez une fois
téléchargé = client.beta.files.upload(
    file=("contrat.pdf", open("contrat.pdf", "rb"), "application/pdf"),
)
print(f"Téléchargé: {uploaded.id}")

# 2. Posez plusieurs questions en utilisant le même file_id
questions = [
    "Quelles sont les principales conditions générales?",
    "Quelle est la clause de résiliation?",
    "Résumer l'échéancier des paiements.",
]

pour question en questions:
    réponse = client.beta.messages.create(
        modèle="claude-opus-4-7",
        max_tokens = 16 000,
        messages=[{
            "rôle": "utilisateur",
            "contenu": [
                {"type": "texte", "texte": question},
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": uploaded.id}
                }
            ]
        }],
        bêtas=["files-api-2025-04-14"],
    )
    imprimer(f"\nQ: {question}")
    text = next((b.text pour b dans réponse.content si b.type == "text"), "")
    print(f"A: {texte[:200]}")

# 3. Nettoyer une fois terminé
client.beta.files.delete (uploaded.id)

### python/claude-api/streaming.md

[Télécharger python/claude-api/streaming.md](/skills/claude-api/python/claude-api/streaming.md)

```markdown
# Streaming — Python

## Quick Start

```python
avec client.messages.stream(
    modèle="claude-opus-4-7",
    max_tokens = 64 000,
    messages=[{"role": "user", "content": "Ecrire une histoire"}]
) sous forme de flux:
    pour le texte dans stream.text_stream:
        print(texte, end="", flush=True)

Async

asynchrone avec async_client.messages.stream(
    modèle="claude-opus-4-7",
    max_tokens = 64 000,
    messages=[{"role": "user", "content": "Ecrire une histoire"}]
) sous forme de flux:
    asynchrone pour le texte dans stream.text_stream:
        print(texte, end="", flush=True)

Handling Different Content Types

Claude may return text, thinking blocks, or tool use. Handle each appropriately:

avec client.messages.stream(
    modèle="claude-opus-4-7",
    max_tokens = 64 000,
    thinking={"type": "adaptatif"},
    messages=[{"role": "user", "content": "Analyser ce problème"}]
) sous forme de flux:
    pour l'événement en flux:
        si event.type == "content_block_start":
            if event.content_block.type == "penser":
                print("\n[En pensant...]")
            elif event.content_block.type == "texte":
                print("\n[Réponse:]")

        elif event.type == "content_block_delta":
            si event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

Streaming with Tool Use

The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools:

avec client.messages.stream(
    modèle="claude-opus-4-7",
    max_tokens = 64 000,
    outils=outils,
    messages=messages
) sous forme de flux:
    pour le texte dans stream.text_stream:
        print(texte, end="", flush=True)

    réponse = stream.get_final_message()
    # Continuez l'exécution de l'outil si réponse.stop_reason == "tool_use"

Getting the Final Message

avec client.messages.stream(
    modèle="claude-opus-4-7",
    max_tokens = 64 000,
    messages=[{"role": "user", "content": "Bonjour"}]
) sous forme de flux:
    pour le texte dans stream.text_stream:
        print(texte, end="", flush=True)

    # Recevez le message complet après la diffusion
    final_message = stream.get_final_message()
    print(f"\n\nJetons utilisés: {final_message.usage.output_tokens}")

Streaming with Progress Updates

def stream_with_progress(client, **kwargs):
    """Diffusez une réponse avec des mises à jour de progression."""
    total_jetons = 0
    contenu_parts = []

    avec client.messages.stream(**kwargs) comme flux:
        pour l'événement en flux:
            si event.type == "content_block_delta":
                si event.delta.type == "text_delta":
                    texte = événement.delta.text
                    content_parts.append(texte)
                    print(texte, end="", flush=True)

            elif event.type == "message_delta":
                si event.usage et event.usage.output_tokens ne sont pas None:
                    total_tokens = event.usage.output_tokens

        final_message = stream.get_final_message()

    print(f"\n\n[Jetons utilisés: {total_tokens}]")
    renvoyer "".join(content_parts)

Error Handling in Streams

essaye:
    avec client.messages.stream(
        modèle="claude-opus-4-7",
        max_tokens = 64 000,
        messages=[{"role": "user", "content": "Ecrire une histoire"}]
    ) sous forme de flux:
        pour le texte dans stream.text_stream:
            print(texte, end="", flush=True)
sauf anthropic.APIConnectionError:
    print("\nConnexion perdue. Veuillez réessayer.")
sauf anthropique.RateLimitError:
    print("\nTaux limité. Veuillez patienter et réessayer.")
sauf anthropic.APIStatusError comme e:
    print(f"\nErreur API: {e.status_code}")

Stream Event Types

Best Practices

1. Always flush output — Use flush=True to show tokens immediately
2. Handle partial responses — If the stream is interrupted, you may have incomplete content
3. Track token usage — The message_delta event contains usage information
4. Use timeouts — Set appropriate timeouts for your application
5. Default to streaming — Use .get_final_message() to get the complete response even when streaming, giving you timeout protection without needing to handle individual events

### python/claude-api/tool-use.md

[Télécharger python/claude-api/tool-use.md](/skills/claude-api/python/claude-api/tool-use.md)

_Ressource binaire_

### python/managed-agents/README.md

[Télécharger python/managed-agents/README.md](/skills/claude-api/python/managed-agents/README.md)

_Ressource binaire_

### ruby/claude-api.md

[Télécharger ruby/claude-api.md](/skills/claude-api/ruby/claude-api.md)

```markdown
# Claude API — Ruby

> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby.

## Installation

```bash
gem installer anthropique

Client Initialization

exiger "anthropique"

# Par défaut (utilise la variable d'environnement ANTHROPIC_API_KEY)
client = Anthropic::Client.new

# Clé API explicite
client = Anthropic::Client.new(api_key: "votre-api-key")

Basic Message Request

message = client.messages.create(
  modèle::"claude-opus-4-7",
  max_tokens: 16 000,
  messages: [
    { rôle: "utilisateur", contenu: "Quelle est la capitale de la France?" }
  ]
)
# le contenu est un tableau d'objets blocs polymorphes (TextBlock, ThinkingBlock,
# ToolUseBlock,...)..type est un symbole — à comparer avec:text, pas "text".
# .text déclenche NoMethodError sur les entrées non TextBlock.
message.content.each fait |bloquer|
  met block.text si block.type ==:text
fin

Streaming

flux = client.messages.stream(
  modèle::"claude-opus-4-7",
  max_tokens: 64 000,
  messages: [{ rôle: "utilisateur", contenu: "Écrire un haïku" }]
)

flux.text.each { |texte| imprimer(texte) }

Tool Use

The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution.

Tool Runner (Beta)

classe GetWeatherInput < Anthropic:: BaseModel
  obligatoire:location, String, doc: "Ville et état, par exemple San Francisco, Californie"
fin

classe GetWeather < Anthropic:: BaseTool
  doc "Obtenir la météo actuelle pour un emplacement"

  input_schema GetWeatherInput

  appel def (entrée)
    "Le temps à #{input.location} est ensoleillé et 72°F."
  fin
fin

client.beta.messages.tool_runner(
  modèle::"claude-opus-4-7",
  max_tokens: 16 000,
  outils: [GetWeather.new],
  messages: [{ rôle: "utilisateur", contenu: "Quel temps fait-il à San Francisco?" }]
).each_message faire |message|
  met message.content
fin

Manual Loop

See the shared tool use concepts for the tool definition format and agentic loop pattern.

Prompt Caching

system_: (trailing underscore — avoids shadowing Kernel#system) takes an array of text blocks; set cache_control on the last block. Plain hashes work via the OrHash type alias. For placement patterns and the silent-invalidator audit checklist, see shared/prompt-caching.md.

message = client.messages.create(
  modèle::"claude-opus-4-7",
  max_tokens: 16 000,
  système_: [
    { tapez: "texte", texte: long_system_prompt, cache_control: { tapez: "éphémère" } }
  ],
  messages: [{ rôle: "utilisateur", contenu: "Résumer les points clés" }]
)

For 1-hour TTL: cache_control: { type: "ephemeral", ttl: "1h" }. There's also a top-level cache_control: on messages.create that auto-places on the last cacheable block.

Verify hits via message.usage.cache_creation_input_tokens / message.usage.cache_read_input_tokens.

### ruby/managed-agents/README.md

[Télécharger ruby/managed-agents/README.md](/skills/claude-api/ruby/managed-agents/README.md)

_Ressource binaire_

### partagé/agent-design.md

[Télécharger shared/agent-design.md](/skills/claude-api/shared/agent-design.md)

_Ressource binaire_

### partagé/codes-d'erreur.md

[Télécharger shared/error-codes.md](/skills/claude-api/shared/error-codes.md)

_Ressource binaire_

### partagé/live-sources.md

[Télécharger shared/live-sources.md](/skills/claude-api/shared/live-sources.md)

_Ressource binaire_

### agents-api-reference.md partagés/gérés

[Télécharger shared/managed-agents-api-reference.md](/skills/claude-api/shared/managed-agents-api-reference.md)

_Ressource binaire_

### agents-clients-partagés/gérés-patterns.md

[Télécharger shared/managed-agents-client-patterns.md](/skills/claude-api/shared/managed-agents-client-patterns.md)

_Ressource binaire_

### partagé/géré-agents-core.md

[Télécharger shared/managed-agents-core.md](/skills/claude-api/shared/managed-agents-core.md)

_Ressource binaire_

### environnements-agents-partagés/gérés.md

[Télécharger shared/managed-agents-environments.md](/skills/claude-api/shared/managed-agents-environments.md)

_Ressource binaire_

### agents-events-partagés/gérés.md

[Télécharger shared/managed-agents-events.md](/skills/claude-api/shared/managed-agents-events.md)

_Ressource binaire_

### mémoire-agents-partagée/gérée.md

[Télécharger shared/managed-agents-memory.md](/skills/claude-api/shared/managed-agents-memory.md)

_Ressource binaire_

### agents-partagés/gérés-multiagent.md

[Télécharger shared/managed-agents-multiagent.md](/skills/claude-api/shared/managed-agents-multiagent.md)

_Ressource binaire_

### agents-onboarding-partagés/gérés.md

[Télécharger shared/managed-agents-onboarding.md](/skills/claude-api/shared/managed-agents-onboarding.md)

_Ressource binaire_

### résultats-agents-partagés/gérés.md

[Télécharger shared/managed-agents-outcomes.md](/skills/claude-api/shared/managed-agents-outcomes.md)

_Ressource binaire_

### vue d'ensemble des agents partagés/gérés.md

[Télécharger shared/managed-agents-overview.md](/skills/claude-api/shared/managed-agents-overview.md)

_Ressource binaire_

### outils-agents-partagés/gérés.md

[Télécharger shared/managed-agents-tools.md](/skills/claude-api/shared/managed-agents-tools.md)

_Ressource binaire_

### agents-webhooks partagés/gérés.md

[Télécharger shared/managed-agents-webhooks.md](/skills/claude-api/shared/managed-agents-webhooks.md)

```markdown
# Managed Agents — Webhooks

Anthropic can POST to your HTTPS endpoint when a Managed Agents resource changes state — an alternative to holding an SSE stream or polling. Payloads are **thin** (event type + resource IDs only); on receipt, fetch the resource for current state. Every delivery is HMAC-signed.

> **Direction matters.** This page covers *Anthropic → you* notifications about session/vault state. It does **not** cover *third-party → you* webhooks that *trigger* a session (e.g. a GitHub push handler that calls `sessions.create()`) — that's ordinary application code on your side with no Anthropic-specific wire format.

---

## Register an endpoint (Console only)

Console → **Manage → Webhooks**. There is no programmatic endpoint-management API yet. Secret rotation is supported from the same page.

| Field | Constraint |
|---|---|
| URL | HTTPS on port 443, publicly resolvable hostname |
| Event types | Subscribe per `data.type` — you only receive subscribed types (plus test events) |
| Signing secret | `whsec_`-prefixed, 32 bytes, **shown once at creation** — store it |

---

## Verify the signature

Every delivery is HMAC-signed. **Use the SDK's `client.beta.webhooks.unwrap()`** — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the `whsec_` secret from `ANTHROPIC_WEBHOOK_SIGNING_KEY`.

```python
importation anthropique
de l'importation de flacons Flacon, demande

client = anthropic.Anthropic() # lit ANTHROPIC_WEBHOOK_SIGNING_KEY depuis l'environnement
application = Flacon (__nom__)


@app.route("/webhook", méthodes=["POST"])
def webhook():
    essaye:
        event = client.beta.webhooks.unwrap(
            request.get_data(as_text=True),
            en-têtes=dict(request.headers),
        )
    sauf exception:
        renvoie "signature invalide", 400

    si event.id dans saw_event_ids: # tentatives de déduplication – l'identifiant est par événement, pas par livraison
        retourner "", 204
    vu_event_ids.add(event.id)

    correspond à event.data.type:
        cas "session.status_idled":
            session = client.beta.sessions.retrieve(event.data.id)
            notify_user (session)
        cas "vault_credential.refresh_failed":
            alert_oncall(event.data.id)

    retourner "", 204

Pass the raw request body to unwrap() — frameworks that re-serialize JSON (Express .json(), Flask .get_json()) change the bytes and break the MAC. For other languages, look up the beta.webhooks.unwrap binding in the SDK repo (shared/live-sources.md); don't hand-roll verification.

Payload envelope

{
  "type": "événement",
  "id": "event_01ABC...",
  "created_at": "2026-03-18T14:05:22Z",
  "données": {
    "type": "session.status_idled",
    "id": "session_01XYZ...",
    "organisation_id": "8a3d2f1e-...",
    "workspace_id": "c7b0e4d9-..."
  }
}

Switch on data.type, fetch the resource by data.id, return any 2xx to acknowledge. created_at is when the state transition happened, not when the webhook fired.

Supported data.type values

Delivery behavior & pitfalls

• No ordering guarantee. session.status_idled may arrive before session.outcome_evaluation_ended even if the evaluation finished first. Sort by envelope created_at if order matters.
• Retries carry the same event.id. At least one retry on non-2xx. Dedupe on event.id.
• 3xx is failure. Redirects are not followed — update the URL in Console if your endpoint moves.
• Auto-disable after ~20 consecutive failed deliveries, or immediately if the hostname resolves to a private IP or returns a redirect. Re-enable manually in Console.
• Thin payload is intentional. Don't expect stop_reason, outcome_evaluations, credential secrets, etc. on the webhook body — fetch the resource.

### partagé/model-migration.md

[Télécharger shared/model-migration.md](/skills/claude-api/shared/model-migration.md)

_Ressource binaire_

### partagé/modèles.md

[Télécharger shared/models.md](/skills/claude-api/shared/models.md)

_Ressource binaire_

### partagé/prompt-caching.md

[Télécharger shared/prompt-caching.md](/skills/claude-api/shared/prompt-caching.md)

_Ressource binaire_

### partagé/tool-use-concepts.md

[Télécharger shared/tool-use-concepts.md](/skills/claude-api/shared/tool-use-concepts.md)

_Ressource binaire_

### dactylographié/claude-api/README.md

[Télécharger typescript/claude-api/README.md](/skills/claude-api/typescript/claude-api/README.md)

_Ressource binaire_

### dactylographié/claude-api/batches.md

[Télécharger typescript/claude-api/batches.md](/skills/claude-api/typescript/claude-api/batches.md)

```markdown
# Message Batches API — TypeScript

The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.

## Key Facts

- Up to 100,000 requests or 256 MB per batch
- Most batches complete within 1 hour; maximum 24 hours
- Results available for 29 days after creation
- 50% cost reduction on all token usage
- All Messages API features supported (vision, tools, caching, etc.)

---

## Create a Batch

```typescript
importer Anthropic depuis "@anthropic-ai/sdk";

const client = new Anthropic();

const messageBatch = attendre client.messages.batches.create({
  demandes: [
    {
      custom_id: "requête-1",
      paramètres: {
        modèle: "claude-opus-4-7",
        max_tokens: 16 000,
        messages: [
          { rôle: "utilisateur", contenu: "Résumer les impacts du changement climatique" },
        ],
      },
    },
    {
      custom_id: "requête-2",
      paramètres: {
        modèle: "claude-opus-4-7",
        max_tokens: 16 000,
        messages: [
          { rôle: "utilisateur", contenu: "Expliquer les bases de l'informatique quantique" },
        ],
      },
    },
  ],
});

console.log(`Batch ID: ${messageBatch.id}`);
console.log(`Status: ${messageBatch.processing_status}`);

Poll for Completion

laisser lot;
tandis que (vrai) {
  batch = attendre client.messages.batches.retrieve(messageBatch.id);
  if (batch.processing_status === "terminé") break;
  console.log(
   `Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`,
  );
  wait new Promise((resolve) => setTimeout(resolve, 60_000));
}

console.log("Lot terminé!");
console.log(`Succeeded: ${batch.request_counts.succeeded}`);
console.log(`Errored: ${batch.request_counts.errored}`);

Retrieve Results

pour wait (résultat const de wait client.messages.batches.results(
  messageBatch.id,
)) {
  commutateur (result.result.type) {
    cas "réussi":
      console.log(
       `[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`,
      );
      casser;
    cas "erré":
      if (result.result.error.type === "invalid_request") {
        console.log(`[${result.custom_id}] Validation error - fix and retry`);
      } autre {
        console.log(`[${result.custom_id}] Server error - safe to retry`);
      }
      casser;
    cas "expiré":
      console.log(`[${result.custom_id}] Expired - resubmit`);
      casser;
  }
}

Cancel a Batch

const annulé = attendre client.messages.batches.cancel(messageBatch.id);
console.log(`Status: ${cancelled.processing_status}`); // "annulation"

### dactylographié/claude-api/files-api.md

[Télécharger typescript/claude-api/files-api.md](/skills/claude-api/typescript/claude-api/files-api.md)

```markdown
# Files API — TypeScript

The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls.

**Beta:** Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically).

## Key Facts

- Maximum file size: 500 MB
- Total storage: 100 GB per organization
- Files persist until deleted
- File operations (upload, list, delete) are free; content used in messages is billed as input tokens
- Not available on Amazon Bedrock or Google Vertex AI

---

## Upload a File

```typescript
importer Anthropic, { toFile } depuis "@anthropic-ai/sdk";
importer fs depuis "fs";

const client = new Anthropic();

const téléchargé = attendre client.beta.files.upload({
  fichier: attendre toFile(fs.createReadStream("report.pdf"), non défini, {
    tapez: "application/pdf",
  }),
  bêtas: ["files-api-2025-04-14"],
});

console.log(`File ID: ${uploaded.id}`);
console.log(`Size: ${uploaded.size_bytes} bytes`);

Use a File in Messages

PDF / Text Document

réponse const = attendre client.beta.messages.create({
  modèle: "claude-opus-4-7",
  max_tokens: 16 000,
  messages: [
    {
      rôle: "utilisateur",
      contenu: [
        { type: "text", text: "Résumez les principales conclusions de ce rapport." },
        {
          tapez: "document",
          source: { type: "fichier", file_id: uploaded.id },
          titre: "Rapport Q4",
          citations: { activé: vrai },
        },
      ],
    },
  ],
  bêtas: ["files-api-2025-04-14"],
});

console.log(response.content[0].text);

Manage Files

List Files

const files = attendre client.beta.files.list({
  bêtas: ["files-api-2025-04-14"],
});
pour (const f de files.data) {
  console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`);
}

Delete a File

attendre client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", {
  bêtas: ["files-api-2025-04-14"],
});

Download a File

réponse const = attendre client.beta.files.download(
  "fichier_011CNha8iCJcU1wXNR6q4V8w",
  { bêtas: ["files-api-2025-04-14"] },
);
const content = Buffer.from (attendre réponse.arrayBuffer());
wait fs.promises.writeFile("output.txt", content);

### dactylographié/claude-api/streaming.md

[Télécharger typescript/claude-api/streaming.md](/skills/claude-api/typescript/claude-api/streaming.md)

```markdown
# Streaming — TypeScript

## Quick Start

```typescript
const stream = client.messages.stream({
  modèle: "claude-opus-4-7",
  max_tokens: 64 000,
  messages: [{ rôle: "utilisateur", contenu: "Écrire une histoire" }],
});

pour wait (événement const du flux) {
  si (
    event.type === "content_block_delta" &&
    event.delta.type === "text_delta"
  ) {
    process.stdout.write(event.delta.text);
  }
}

Handling Different Content Types

const stream = client.messages.stream({
  modèle: "claude-opus-4-7",
  max_tokens: 64 000,
  en pensant: { type: "adaptatif" },
  messages: [{ rôle: "utilisateur", contenu: "Analyser ce problème" }],
});

pour wait (événement const du flux) {
  commutateur (événement.type) {
    cas "content_block_start":
      commutateur (event.content_block.type) {
        cas "penser":
          console.log("\n[Pensée...]");
          casser;
        cas "texte":
          console.log("\n[Réponse:]");
          casser;
      }
      casser;
    cas "content_block_delta":
      commutateur (event.delta.type) {
        cas "thinking_delta":
          process.stdout.write(event.delta.thinking);
          casser;
        cas "text_delta":
          process.stdout.write(event.delta.text);
          casser;
      }
      casser;
  }
}

Streaming with Tool Use (Tool Runner)

Use the tool runner with stream: true. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events:

importer Anthropic depuis "@anthropic-ai/sdk";
importer { betaZodTool } depuis "@anthropic-ai/sdk/helpers/beta/zod";
importer { z } depuis "zod";

const client = new Anthropic();

const getWeather = betaZodTool({
  nom: "get_weather",
  description: "Obtenir la météo actuelle pour un emplacement",
  schéma d'entrée: z.object({
    location: z.string().describe("Ville et état, par exemple San Francisco, Californie"),
  }),
  exécuter: async ({ emplacement }) =>`72°F and sunny in ${location}`,
});

const runner = client.beta.messages.toolRunner({
  modèle: "claude-opus-4-7",
  max_tokens: 64 000,
  outils: [getWeather],
  messages: [
    { rôle: "utilisateur", contenu: "Quel temps fait-il à Paris et à Londres?" },
  ],
  flux: vrai,
});

// Boucle externe: chaque itération du programme d'exécution d'outil
pour wait (const messageStream du coureur) {
  // Boucle interne: diffuse les événements pour cette itération
  pour wait (événement const de messageStream) {
    commutateur (événement.type) {
      cas "content_block_delta":
        commutateur (event.delta.type) {
          cas "text_delta":
            process.stdout.write(event.delta.text);
            casser;
          cas "input_json_delta":
            // Entrée d'outil en cours de streaming
            pause;
        }
        casser;
    }
  }
}

Getting the Final Message

const stream = client.messages.stream({
  modèle: "claude-opus-4-7",
  max_tokens: 64 000,
  messages: [{ rôle: "utilisateur", contenu: "Bonjour" }],
});

pour wait (événement const du flux) {
  // Traiter les événements...
}

const finalMessage = wait stream.finalMessage();
console.log(`Tokens used: ${finalMessage.usage.output_tokens}`);

Stream Event Types

Best Practices

1. Always flush output — Use process.stdout.write() for immediate display
2. Handle partial responses — If the stream is interrupted, you may have incomplete content
3. Track token usage — The message_delta event contains usage information
4. Use finalMessage() — Get the complete Anthropic.Message object even when streaming. Don't wrap .on() events in new Promise() — finalMessage() handles all completion/error/abort states internally
5. Buffer for web UIs — Consider buffering a few tokens before rendering to avoid excessive DOM updates
6. Use stream.on("text", ...) for deltas — The text event provides just the delta string, simpler than manually filtering content_block_delta events
7. For agentic loops with streaming — See the Streaming Manual Loop section in tool-use.md for combining stream() + finalMessage() with a tool-use loop

Raw SSE Format

If using raw HTTP (not SDKs), the stream returns Server-Sent Events:

événement: message_start
données: {"type": "message_start", "message": {"id": "msg_...", "type": "message",...}}

événement: content_block_start
données: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

événement: content_block_delta
données: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Bonjour"}}

événement: content_block_stop
données: {"type": "content_block_stop", "index": 0}

événement: message_delta
données: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}

événement: message_stop
données: {"type": "message_stop"}

### dactylographié/claude-api/tool-use.md

[Télécharger typescript/claude-api/tool-use.md](/skills/claude-api/typescript/claude-api/tool-use.md)

_Ressource binaire_

### dactylographié/managed-agents/README.md

[Télécharger typescript/managed-agents/README.md](/skills/claude-api/typescript/managed-agents/README.md)

_Ressource binaire_

## Voir dans GitHub

[Voir dans GitHub](https://github.com/anthropics/skills/tree/main/claude-api)