Votre premier appel API

Avant de parler d’agents, il faut savoir lire une requête et sa réponse. Cette leçon reprend le quickstart officiel en TypeScript : une requête, une réponse, et ce que chaque champ veut dire.

Préparer le projet

Exportez votre clé d’API dans une variable d’environnement. Le SDK lit ANTHROPIC_API_KEY automatiquement, ce qui évite de l’écrire dans le code.

export ANTHROPIC_API_KEY="votre-cle-api"
mkdir claude-quickstart && cd claude-quickstart
npm init -y
npm pkg set type=module
npm install @anthropic-ai/sdk

La requête

Créez quickstart.ts :

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1000,
  messages: [
    {
      role: "user",
      content: "What should I search for to find the latest developments in renewable energy?",
    },
  ],
});

for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

Puis lancez-le avec npx tsx quickstart.ts.

Trois champs suffisent à une requête :

• model : l’identifiant du modèle, ici Claude Opus 5.5. La leçon suivante explique comment choisir.
• max_tokens : le plafond de jetons que la réponse peut produire. Si Claude l’atteint, la réponse est coupée.
• messages : la conversation, une liste de messages qui ont chacun un rôle (user ou assistant) et un contenu. Le premier message est toujours celui de l’utilisateur.

La réponse

La réponse est un objet message. Les champs qui comptent :

• content : une liste de blocs typés. Ici un seul bloc text, mais vous rencontrerez aussi des blocs tool_use (Claude demande à utiliser un outil) ou thinking (sa réflexion). D’où la boucle du code : on vérifie le type de chaque bloc avant de lire son texte, et TypeScript l’exige d’ailleurs.
• stop_reason : pourquoi Claude s’est arrêté. Les valeurs à connaître :

• usage : les jetons consommés en entrée et en sortie, la base de votre facture.

Une API sans mémoire

L’API ne garde rien d’une requête à l’autre : vous renvoyez tout l’historique à chaque fois. Pour une conversation à plusieurs tours, vous ajoutez la réponse de Claude (rôle assistant) puis la nouvelle question de l’utilisateur, et vous renvoyez la liste complète. Le champ system porte les instructions générales de votre application, comme « Tu es un assistant de programmation ; donne tes exemples en Python ».

Les erreurs

Le SDK lève des exceptions typées. Testez-les de la plus précise à la plus générale, plutôt que de chercher des mots dans le message d’erreur :

try {
  const response = await client.messages.create({ /* ... */ });
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    // 429 : trop de requêtes, réessayer plus tard
  } else if (error instanceof Anthropic.AuthenticationError) {
    // clé invalide
  } else if (error instanceof Anthropic.BadRequestError) {
    // requête mal formée (400)
  } else if (error instanceof Anthropic.APIError) {
    console.error(`Erreur API ${error.status}`, error.message);
  }
}

Par défaut, le SDK réessaie déjà deux fois les erreurs passagères (429, erreurs serveur, coupures réseau).

Pour les réponses longues

Une requête qui produit une longue réponse, ou qui fixe un max_tokens élevé, risque d’atteindre le délai d’attente HTTP. La documentation recommande alors le streaming : la réponse arrive au fil de l’eau, et l’aide finalMessage() du SDK reconstitue le message complet à la fin si vous n’avez pas besoin des événements intermédiaires.

À vous de jouer

Votre premier appel. Lancez l’exemple de cette leçon, puis affichez stop_reason et usage. Ajoutez un second tour à la conversation en renvoyant tout l’historique, et provoquez volontairement une erreur d’authentification avec une clé erronée pour lire sa classe d’erreur.

Sources officielles : Your first API call (Claude Academy) · Get started with Claude · Using the Messages API

Points clés à retenir

• Une requête : model, max_tokens, messages ; le SDK lit la clé dans ANTHROPIC_API_KEY
• La réponse est une liste de blocs typés (text, tool_use, thinking…) et un stop_reason qui dit pourquoi Claude s’est arrêté
• L’API est sans état : renvoyez tout l’historique à chaque requête
• Exceptions typées pour les erreurs, streaming pour les réponses longues