Claude et Python : maîtrisez l'API pour des intégrations fluides

Introduction à l'intégration de Claude avec Python

Intégrer Claude dans une application Python peut sembler complexe, mais les étapes initiales sont étonnamment simples. La création d'un compte et l'exécution d'un premier appel API peuvent être réalisées en quelques minutes grâce à la documentation officielle. Cependant, des questions pratiques se posent rapidement :

• Que contient exactement l'objet de réponse ?
• Comment diffuser les réponses pour que les utilisateurs puissent les voir au fur et à mesure de leur génération ?
• Comment structurer les invites et gérer les réponses dans une application en production ?

Le SDK Python de Claude facilite grandement l'interaction avec l'API sous-jacente. Il offre des objets de réponse typés, une gestion intégrée des tentatives et une interface simplifiée pour travailler avec l'API Messages. Cet article vous guide à travers la configuration, votre premier appel API, la lecture de la réponse, les invites système et le streaming. À la fin, vous disposerez d'une base fonctionnelle solide.

Prérequis et Installation

Pour commencer, vous aurez besoin de Python 3.9 ou d'une version supérieure, d'un compte gratuit sur Claude Console et d'une clé API obtenue depuis la section Paramètres > Clés API de la Console. Vous pouvez ajouter 5 $ de crédits pour expérimenter avec tout ce qui est abordé dans cet article.

Une fois ces éléments en place, installez le SDK avec la commande suivante :

pip install [anthropic](/dossier/anthropic)

Il est crucial de ne jamais coder votre clé API directement dans vos fichiers source. Stockez-la plutôt comme une variable d'environnement :

export ANTHROPIC_API_KEY="VOTRE-CLÉ-API-IÇI"

Alternativement, vous pouvez l'ajouter à un fichier .env à la racine de votre projet si vous utilisez python-dotenv. Le SDK lira la ANTHROPIC_API_KEY depuis votre environnement, vous n'avez donc pas besoin de la passer explicitement dans votre code.

Réaliser Votre Premier Appel API

Chaque interaction commence par client.messages.create(). Par exemple, demandons à Claude d'expliquer ce qu'est une fenêtre de contexte, un concept essentiel pour utiliser l'API.

Vous devez fournir trois éléments : l'ID du modèle, une limite de max_tokens, et une liste de messages. Cette liste est toujours constituée de dictionnaires, chacun avec une clé "role" et une clé "content".

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "En une phrase, qu'est-ce qu'une fenêtre de contexte ?"}]
)
print(response.content[0].text)

Le champ model doit contenir l'ID exact du modèle. max_tokens impose une limite stricte sur le nombre de tokens que Claude produira ; la réponse s'arrêtera là même si elle n'est pas complète, donc fixez-la suffisamment haute pour des requêtes ouvertes. La liste de messages doit toujours commencer par un tour "user".

Une fenêtre de contexte est la quantité maximale de texte (mesurée en tokens) qu'un modèle de langage peut traiter et considérer à un moment donné, englobant à la fois votre entrée et sa sortie.

Comprendre l'Objet de Réponse

La réponse de messages.create() est un objet Message typé. Il est utile d'examiner la structure complète avant de construire quoi que ce soit dessus.

Remplacez la ligne de print dans l'exemple précédent par :

print(response)

Cela vous donnera l'objet complet :

id='msg_01XFDUDYJgAACzvnptvVoYEL',
role='assistant',
content=[TextBlock(text='A context window is...', type='text')],
model='claude-sonnet-5',
stop_reason='end_turn',
stop_sequence=None,
usage=Usage(input_tokens=19, output_tokens=42)

Certains champs ici sont plus importants qu'ils ne le paraissent. stop_reason indique pourquoi Claude a cessé de générer. end_turn signifie que Claude a terminé de son propre chef. Si vous voyez max_tokens, la réponse a été interrompue par votre limite, et vous devrez peut-être l'augmenter ou repenser l'invite.

Le champ usage suit à la fois les tokens d'entrée et de sortie pour la requête. C'est ainsi qu'Anthropic calcule la facturation, et c'est aussi comment vous détectez quand une invite s'approche trop près de la limite de contexte du modèle. content est une liste — dans les réponses textuelles standard, elle a toujours un élément, un TextBlock — donc response.content[0].text est la manière idiomatique d'extraire le texte.

Utiliser des Invites Système

Une invite système vous permet de donner à Claude un rôle persistant, de définir des contraintes ou de fournir un contexte qui doit s'appliquer à l'ensemble de la conversation. Vous la passez en tant que paramètre système de haut niveau — séparé de la liste de messages, pas en tant que message lui-même.

Ici, nous configurons Claude pour agir en tant que réviseur de code qui ne répond qu'en Python et évite les explications générales :

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5",
    messages=[{"role": "system", "content": "Vous êtes un réviseur de code Python. Répondez uniquement avec du code Python corrigé ou amélioré. Ne pas expliquer les changements à moins que l'utilisateur ne le demande explicitement."},
              {"role": "user", "content": "def get_user(id):\n    db = connect()\n    return db.query('SELECT * FROM users WHERE id=' + id)"}]
)
print(response.content[0].text)

L'invite système se trouve au-dessus de la conversation dans le contexte de Claude. Elle conserve la même autorité tout au long de tous les tours, donc les instructions de rôle, les règles de formatage et les contraintes de domaine que vous définissez ici persistent sans que vous ayez besoin de les répéter dans chaque message.

Streaming des Réponses

Pour les requêtes où Claude peut prendre quelques secondes pour répondre, le streaming vous permet d'afficher le texte au fur et à mesure de son arrivée au lieu d'attendre la réponse complète. Le SDK expose cela via client.messages.stream(), utilisé comme un gestionnaire de contexte.

L'itérateur text_stream renvoie des morceaux de texte individuels en temps réel. Chaque morceau est un fragment de chaîne, pas une phrase complète. Vous passez end="" et flush=True à print() pour que la sortie apparaisse en continu plutôt que d'être mise en mémoire tampon :

import anthropic

client = anthropic.Anthropic()
with client.messages.stream(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Expliquez-moi ce qui se passe lorsque une liste Python dépasse sa capacité initiale."}]
) as stream:
    for chunk in stream.text_stream:
        print(chunk, end="", flush=True)
print()  # nouvelle ligne après la fin du stream

Le gestionnaire de contexte garantit que la connexion HTTP est fermée proprement lorsque le bloc se termine, même si une exception est levée en cours de streaming. Si vous avez besoin de l'objet Message complet après le streaming — y compris les comptes d'utilisation des tokens — appelez stream.get_final_message() avant la fermeture du bloc.

Les listes Python sont des tableaux dynamiques. Lorsque vous ajoutez un élément et que la liste n'a plus de place, Python alloue un nouveau bloc de mémoire plus grand — généralement 1,125x la taille actuelle — copie tous les éléments existants dedans et libère l'ancien bloc. Cette opération est O(n) dans le pire des cas, mais comme elle se produit rarement par rapport au nombre d'ajouts, le coût amorti par ajout reste O(1). Vous pouvez pré-allouer de la capacité avec une compréhension de liste ou en passant un itérable au constructeur de liste si vous connaissez la taille finale à l'avance.

Vous avez maintenant les éléments de base : requêtes, réponses structurées, invites système et streaming.

Ensuite, vous pouvez apprendre à propos de la gestion des erreurs, de l'utilisation des tokens et des conversations multi-tours. Comme l'API est sans état, vous devez envoyer l'historique de la conversation avec chaque requête. La documentation du SDK montre l'approche recommandée.

La référence API inclut également des fonctionnalités telles que des sorties structurées et l'utilisation d'outils. Bonne exploration !