Comment construire un chatbot avec l'API Claude en 2026

Auparavant, créer un chatbot impliquait de jongler avec des classificateurs d’intentions, des arborescences de dialogue et une multitude de cas particuliers. Grâce à une API de modèle linguistique moderne, c’est le modèle qui se charge de la partie la plus complexe — comprendre et répondre — et votre rôle se limite à la mise en place de l’infrastructure autour de celui-ci. Avec l’API Claude, vous pouvez disposer d’un chatbot véritablement performant en bien moins d’une heure.

Ce guide présente les concepts et le code : configuration, conduite d'une conversation, gestion du comportement, transmission des réponses en continu et optimisation des coûts.

Étape 1 : Mise en place

Il vous faut deux éléments : une clé API et le SDK.

1. Obtenir une clé API — Créez un compte sur la console Anthropic et générez une clé API. Gardez-la secrète : enregistrez-la dans une variable d'environnement, ne l'intégrez jamais directement dans le code et ne la soumettez jamais au contrôle de version.
2. Installer le SDK — Anthropic propose des SDK officiels. Pour Python :

pip install anthropic

(Un SDK Node.js est également disponible ; les concepts présentés ci-dessous sont identiques.)

Étape 2 : Votre premier message

Le cœur de l'API Claude est le API Messages. Vous envoyez une liste de messages ; Claude renvoie le suivant. Voici l'appel le plus simple possible :

from anthropic import Anthropic

client = Anthropic()  # lit la variable d'environnement ANTHROPIC_API_KEY

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
 {"role": "user", "content": "Bonjour ! En quoi peux-tu m'aider ?"}
    ],
)

print(response.content[0].text)

C'est un chatbot qui fonctionne — même s'il est très tête en l'air. modèle permet de choisir quel Claude utiliser, max_tokens limite la longueur de la réponse, et messages Voici le déroulement de la conversation jusqu'à présent.

Étape 3 : Donnez-lui un souvenir

L'exemple ci-dessus ne dispose d'aucune mémoire : chaque appel est indépendant. Pour mener une véritable conversation, vous Conserver l'historique et le renvoyer à chaque tour. L'API elle-même est sans état : elle ne connaît que ce que vous lui envoyez.

Le principe : maintenir un messages liste, ajouter chaque message de l'utilisateur et chaque réponse de Claude, puis transmettre l'intégralité de la liste à chaque appel.

from anthropic import Anthropic

client = Anthropic()
messages = []

while True:
    user_input = input("Vous : ")
    if user_input.lower() == "quit":
 break

 messages.append({"role": "user", "content": user_input})

    response = client.messages.create(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 messages=messages,
    )

    reply = response.content[0].text
    print(f"Claude : {reply}")

 messages.append({"role": "assistant", "content": reply})

C'est désormais un véritable chatbot : il se souvient de tout ce qui s'est dit auparavant dans la conversation, car l'historique est transmis à chaque tour de parole.

Étape 4 : Définir sa personnalité à l'aide d'une invite système

Un assistant générique correspond rarement à ce que vous recherchez. Le invite du système définit le rôle, le ton et les règles du bot. Il est transmis sous forme de système paramètre, et non comme un message.

SYSTEM_PROMPT = """Vous êtes un conseiller client sympathique pour un service d’abonnement
au café. Soyez chaleureux, concis et serviable. Si un client vous pose
une question sur un sujet que vous ne maîtrisez pas, dites-lui que vous allez le mettre en relation avec un
conseiller humain. Ne parlez jamais des concurrents."""

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=SYSTEM_PROMPT,
    messages=messages,
)

Les messages du système constituent votre principal outil pour orienter le comportement des utilisateurs : consacrez-y du temps. Précisez clairement le rôle du bot, le ton à adopter, ce qu’il doit faire en cas de doute, ainsi que les limites strictes à respecter.

Étape 5 : Diffuser la réponse en continu

Dans les exemples ci-dessus, vous devez attendre que la réponse soit complète avant que quoi que ce soit ne s'affiche. Les véritables interfaces de chat fonctionnent en flux continu : le texte s'affiche mot à mot. Le SDK facilite grandement cette fonctionnalité :

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=SYSTEM_PROMPT,
    messages=messages,
) as stream:
    for text in stream.text_stream:
 print(text, end="", flush=True)

Le streaming n'accélère pas la génération, mais il rend le bot sentir beaucoup plus réactif, car l'utilisateur voit immédiatement le résultat.

Étape 6 : Réduire les coûts grâce à une mise en cache rapide

Les appels API sont facturés au nombre de jetons, et un chatbot renvoie à chaque tour une grande partie du même texte : l'invite du système et un historique de conversation qui ne cesse de s'allonger. Mise en cache des invites vous permet de marquer les parties stables de la ligne de commande afin que l'API les réutilise au lieu de les retraiter, ce qui réduit considérablement à la fois les coûts et la latence.

Vous ajoutez un marqueur de mise en cache au contenu que vous souhaitez mettre en cache — généralement l'invite du système et tout contexte long et fixe :

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
 {
 "type": "text",
 "text": SYSTEM_PROMPT,
 "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=messages,
)

Pour tout chatbot traitant un trafic réel, activez la mise en cache des messages dès le départ : c'est l'une des optimisations les plus efficaces qui soient, et son activation ne coûte rien.

Choisir un modèle

Claude se décline en plusieurs niveaux. En règle générale :

• Un modèle rapide et équilibré (comme l'offre « Sonnet ») constitue le choix par défaut idéal pour la plupart des chatbots : une qualité irréprochable, une bonne rapidité et un coût raisonnable.
• Le modèle le plus performant (le niveau « Opus ») s'avère utile lorsque le bot doit effectuer des raisonnements complexes ou accomplir des tâches complexes.
• Un modèle plus petit et plus rapide (le niveau « Haiku ») convient aux bots simples et à fort volume, pour lesquels la rapidité et le coût sont les critères prioritaires.

Commencez par le niveau « équilibré » et ne passez à un niveau supérieur ou inférieur qu’une fois que vous aurez constaté une utilisation réelle.

Passage en production

Le code ci-dessus constitue le cœur du programme. Pour un déploiement réel, ajoutez :

• Une couche Web — intégrer la logique dans un point de terminaison API et y connecter une interface utilisateur de chat.
• Limites historiques — Les conversations peuvent s'étendre à l'infini ; limitez ou résumez les anciens échanges pour éviter que les invites ne deviennent trop longues.
• Gestion des erreurs — gérer les limites de débit et les défaillances temporaires à l'aide de tentatives de réessai.
• Connaissances — pour obtenir une réponse à partir de vos propres données, ajoutez utiliser la génération augmentée par recherche Le bot récupère donc les documents pertinents.
• Sécurité — valider les données saisies et définir des limites claires dans l'invite du système.

Gérer les erreurs et les limites de débit avant que les utilisateurs ne les remarquent

Même un chatbot qui fonctionne sur votre ordinateur portable risque de tomber en panne en environnement de production dès qu'il sera soumis à un trafic réel. L'API Claude signale deux types de défaillances, qui nécessitent des réponses différentes. La première est erreurs temporaires de l'API — celles-ci se présentent sous forme d'exceptions accompagnées d'un code d'état HTTP. La deuxième est une refus, ce qui constitue une réponse tout à fait correcte qui se contente de refuser la demande. La confusion entre ces deux cas est l'erreur de fiabilité la plus courante que l'on observe dans les premiers codes de chatbot.

En ce qui concerne les événements transitoires, deux codes d'état sont particulièrement importants :

• 429 (limite de débit) — vous avez dépassé le quota de requêtes par minute ou de jetons par minute de votre compte. La réponse contient un retry-after En-tête indiquant précisément le nombre de secondes à attendre. Respectez ce délai à la lettre ; si vous attendez moins longtemps, vous obtiendrez simplement un autre code d'erreur 429.
• 529 (surchargé) — L'API d'Anthropic est temporairement saturée pour tous les utilisateurs. Il est impossible d'éviter cela par le biais du code, et les requêtes rejetées (code 529) ne sont pas facturées. Patientez un peu puis réessayez ; n'envoyez jamais de requêtes en rafale vers un point de terminaison surchargé.
• 500 (erreur de serveur) — une erreur interne rare. Traitez-la comme l'erreur 529 : réessayez en respectant un délai d'attente.

La bonne nouvelle, c'est que les SDK officiels réessaient déjà pour vous en cas d'erreurs 429 et 5xx en utilisant un délai d'attente exponentiel (la valeur par défaut est de deux tentatives). Pour un chatbot en production, augmentez ce nombre maximal et laissez le SDK s'en charger plutôt que d'écrire votre propre boucle :

• Remonter max_retries côté client (une valeur comprise entre 4 et 5 est raisonnable pour un chat destiné aux utilisateurs).
• Intercepter les exceptions de type — Erreur de limite de requêtes, Erreur de surcharge, APIError — plutôt que de recourir à une comparaison de chaînes de caractères sur le texte d'erreur, ce qui entraîne des dysfonctionnements silencieux lorsque la formulation change.
• Lorsque toutes les tentatives ont été épuisées, affichez à l'utilisateur un message rassurant du type “ Je suis un peu occupé pour le moment, réessayez dans quelques instants ” plutôt qu'une trace de pile.

Les refus constituent une voie tout à fait distincte. Lorsqu'une réponse est renvoyée avec stop_reason : " refus ", la demande a réussi — Claude a refusé de répondre pour des raisons de sécurité, et sur les modèles actuels, vous n’êtes pas facturé lorsqu’aucun résultat n’a été généré. Il est essentiel de ne pas vous contenter de renvoyer la même conversation : le refus se reproduira. Supprimez ou reformulez plutôt le tour de parole qui a déclenché le refus, ou réinitialisez l’historique, puis affichez un message clair à l’utilisateur. Étant donné qu’un refus est un champ de la réponse et non une exception, le code qui se contente de vérifier fin_tour et utilisation_des_outils on risque de laisser passer cela comme une réponse vide de sens et prêtant à confusion. Il faut toujours ajouter une branche explicite à cet effet.

Intégrez ces trois fonctionnalités — la reprise avec délai d'attente, la gestion des exceptions typées et une branche de refus — et votre chatbot fonctionnera de manière fluide même sous charge, au lieu de tomber en panne de manière spectaculaire devant les personnes pour lesquelles vous l'avez conçu.

FAQ

Comment créer un chatbot avec l'API Claude ?

Installez le SDK d’Anthropic, obtenez une clé API, puis appelez l’API Messages : envoyez une liste de messages et Claude vous renverra une réponse. Pour rendre l’échange conversationnel, conservez vous-même l’historique des messages et renvoyez-le à chaque tour. Ajoutez une invite système pour définir la personnalité et activez la mise à jour en continu pour créer une impression de réactivité.

L'API Claude conserve-t-elle en mémoire les messages précédents ?

Non — l'API est sans état. Elle ne retient que ce que vous lui envoyez dans une requête donnée. Pour doter un chatbot d'une mémoire, votre application doit stocker l'historique des conversations et l'intégrer dans le messages liste à chaque appel.

Qu'est-ce qu'une invite du système ?

L'instruction système est une consigne distincte qui définit le rôle, le ton et les règles du chatbot — par exemple : “ Tu es un assistant d'assistance concis ; en cas de doute, transfère la demande à un humain. ” Elle est transmise sous la forme de système paramètre et constitue le principal moyen de définir le comportement du bot.

Combien coûte l'utilisation d'un chatbot Claude ?

Le coût dépend du modèle et du nombre de tokens traités. Un modèle équilibré est peu coûteux pour un trafic de chat classique. Étant donné que les chatbots renvoient à chaque tour la prompt du système et l'historique qui s'allonge, l'activation de la mise en cache de la prompt peut réduire considérablement les coûts : cela permet de réutiliser les parties stables de la prompt au lieu de les retraiter.

Quel modèle Claude devrais-je utiliser pour un chatbot ?

Pour la plupart des chatbots, commencez par un modèle rapide et équilibré (le niveau « Sonnet ») : il offre une excellente qualité à une vitesse et un coût raisonnables. Utilisez le modèle le plus performant pour les tâches de raisonnement complexes, et un modèle plus petit et plus rapide pour les bots simples traitant un volume élevé de requêtes.

Que signifient les erreurs 429 et 529 de l'API Claude ?

Un code d'erreur 429 signifie que vous avez atteint la limite de débit de votre compte (nombre de requêtes ou de jetons par minute) ; la réponse contient un retry-after En-tête indiquant le temps d'attente. Un code 529 signifie que l'API d'Anthropic est temporairement surchargée pour tous les utilisateurs — ces requêtes ne sont pas facturées et ne peuvent pas être contournées par le code. Ces deux cas nécessitent un recul exponentiel, que les SDK officiels appliquent automatiquement par défaut.

Comment mon chatbot doit-il réagir face à un refus de Claude ?

Un refus est considéré comme une réponse normale et valable, accompagnée de stop_reason : " refus ", ce n'est pas considéré comme une erreur, et vous n'êtes pas facturé lorsqu'aucun résultat n'a été généré. Ne réessayez pas la même requête : elle sera à nouveau refusée. Supprimez ou reformulez le message qui a déclenché l’erreur (ou réinitialisez la conversation), puis affichez une explication claire et conviviale à l’utilisateur. À partir d’Opus 4.7, la réponse inclut également un détails_de_l'arrêt catégorie indiquant quelle politique a été déclenchée.

Dois-je écrire ma propre logique de réessai pour l'API Claude ?

En général, non. Les SDK officiels d'Anthropic réessaient déjà par défaut de traiter les erreurs 429 et 5xx avec un délai d'attente exponentiel, avec deux tentatives par défaut. Pour un chatbot destiné aux utilisateurs, la configuration la plus simple et la plus robuste consiste à déclencher max_retries à environ quatre ou cinq côté client et intercepter les exceptions générées (telles que Erreur de limite de requêtes et Erreur de surcharge) plutôt que de créer manuellement une boucle de recul ou d'effectuer une comparaison sur des chaînes d'erreur.

Conclusion

La création d'un chatbot avec l'API Claude repose principalement sur la mise en place du système, et non sur l'IA. Le modèle se charge de la compréhension et des réponses ; à vous de gérer la boucle. Gardez un messages historique et le renvoyer pour mémoire, utilisez un système Utilisez la fonction « prompt » pour la personnalisation, la fonction « stream » pour la réactivité, et activez la mise en cache des « prompts » pour maîtriser les coûts.

Ce noyau représente effectivement une heure de travail. Le chemin vers la mise en production passe par les tâches d'ingénierie habituelles qui l'entourent : une couche web, la gestion de l'historique, la gestion des erreurs, et la RAG si le bot a besoin de vos données. Commencez par la boucle simple ci-dessus, faites-le parler, puis développez-le à partir de là.