Accéder à l'API — Claude sur Google Cloud (Vertex AI / Agent Platform)

Comprendre le trajet d’une requête n’est pas un détour théorique : c’est ce qui vous permettra de savoir, quand quelque chose ne va pas, où chercher. Une réponse tronquée, une latence anormale et une facture inattendue ont chacune leur origine à une étape précise de ce parcours, et les confondre fait perdre des heures.

Les 5 étapes d’une requête

D'après la leçon « Accessing the API » (Claude Academy, Claude on Google Cloud).

Le client (navigateur, application mobile, script) envoie une demande à votre serveur
Votre serveur reçoit la demande et construit la requête, avec les identifiants Google Cloud de votre projet
Vertex AI, la plateforme de Google Cloud (désormais nommée Agent Platform), vérifie les droits et transmet la requête au modèle
Le modèle traite le prompt et génère une réponse
La réponse remonte : modèle → API → votre serveur → client

Pourquoi un serveur intermédiaire ?

C’est la règle la plus importante de cette leçon, et elle n’a pas d’exception. Si des identifiants Google Cloud se retrouvent dans le code JavaScript d’une page web, n’importe qui peut les lire dans les outils de développement et les utiliser à vos frais — le code envoyé au navigateur est, par construction, lisible par tout le monde. Aucune obfuscation ni variable d’environnement côté front n’y change quoi que ce soit. Votre serveur backend sert de rempart : c’est lui qui détient les identifiants et communique avec Vertex AI. Pour lui parler, vous utilisez un SDK officiel ou de simples requêtes HTTP. Les SDK d’Anthropic prennent en charge Vertex en Python, TypeScript, Java, Go, C#, PHP et Ruby ; en Python, c’est le client AnthropicVertex.

Les champs essentiels d’une requête

Chaque requête demande des identifiants Google Cloud, qui désignent votre projet et l’autorisent à appeler Claude, et trois paramètres :

from anthropic import AnthropicVertex

client = AnthropicVertex(project_id="votre-projet", region="global")

message = client.messages.create(
    model="claude-sonnet-5-5",   # le modèle à utiliser
    max_tokens=4096,                     # plafond de sortie, réflexion comprise
    messages=[                           # La conversation
        {"role": "user", "content": "Bonjour Claude !"}
    ]
)

Les trois paramètres obligatoires :

model : quel modèle utiliser
max_tokens : plafond de tokens pour la réponse, une sécurité et non une cible ; sur les modèles actuels, la réflexion y compte
messages : la liste des messages de la conversation

Ce que fait Claude en interne

Ces quatre étapes internes expliquent deux comportements que l’on constate sans toujours les relier. D’abord, la facturation se fait en tokens et non en mots ou en caractères — c’est la tokenisation qui décide, et un texte français coûte généralement plus de tokens qu’un texte anglais de même longueur. Ensuite, la réponse arrive progressivement parce qu’elle est produite progressivement, un token après l’autre : c’est ce qui rend le streaming possible, et ce qui explique qu’une réponse longue prenne plus de temps qu’une réponse courte.

Tokenisation : le texte est découpé en tokens (morceaux de mots). “Bonjour” peut devenir un ou plusieurs tokens
Embedding : chaque token est converti en un vecteur numérique
Contextualisation : le modèle analyse les relations entre tous les tokens via le mécanisme d’attention
Génération : une couche de sortie calcule la probabilité de chaque token suivant ; le modèle n’en prend pas toujours le plus probable, il mêle probabilité et part d’aléatoire contrôlée pour des réponses naturelles et variées, puis recommence token après token

Le cours officiel l’illustre avec le mot « quantum » : unité physique, mécanique quantique, échelle subatomique ou informatique quantique, c’est la contextualisation qui choisit le sens d’après les mots voisins. Les modèles actuels ajoutent une étape avant la réponse : ils peuvent réfléchir, en produisant des tokens de réflexion facturés comme des tokens de sortie.

Quand Claude arrête-t-il de générer ?

Ce champ mérite d’être lu par votre code, pas seulement consulté en débogage : c’est lui qui distingue une réponse terminée d’une réponse coupée. Une réponse tronquée à cause de max_tokens ressemble en tout point à une réponse normale — texte cohérent, aucune erreur — sauf qu’il lui manque la fin. Sans vérification de stop_reason, vous l’enregistrerez comme complète.

Fin naturelle : le modèle estime avoir terminé (end_turn)
max_tokens atteint : la réponse est coupée à la limite fixée (max_tokens)
Séquence d’arrêt : le modèle a produit une des chaînes de stop_sequences (stop_sequence, leçon 8)
Demande d’outil : Claude veut appeler un outil (tool_use, section 5)
Tour mis en pause : un tour long, avec outils serveur, s’est interrompu et peut reprendre (pause_turn)
Refus : les classificateurs de sécurité sont intervenus (refusal)
Contexte dépassé : la fenêtre de contexte du modèle est pleine (model_context_window_exceeded)

Structure de la réponse

Message(
    id='msg_…',
    type='message',
    role='assistant',
    content=[
        ThinkingBlock(type='thinking', thinking='', signature='…'),   # si le modèle a réfléchi
        TextBlock(type='text', text='Bonjour ! Comment puis-je vous aider ?'),
    ],
    model='claude-sonnet-5-5',
    stop_reason='end_turn',
    usage=Usage(input_tokens=12, output_tokens=15, …),
)

Les champs importants :

content : la réponse générée, une liste de blocs ; sur les modèles actuels, un bloc de réflexion (thinking, au texte vide par défaut) peut précéder le bloc de texte, et une demande d’outil arrive dans un bloc tool_use
stop_reason : pourquoi le modèle s’est arrêté
usage : tokens consommés en entrée et en sortie, réflexion comprise ; c’est la base de votre facture

Pour extraire le texte, on parcourt les blocs et on garde ceux de type text. Le cours officiel lit message.content[0].text, ce qui suffit avec Claude Haiku 4.5 sans réflexion ; avec un modèle qui réfléchit, le premier bloc peut être la réflexion, et ce code plante.

texte = "".join(block.text for block in message.content if block.type == "text")

À vous de jouer

Repérer les étapes. Pour une application de chat de votre choix (site, appli mobile), dessinez les cinq étapes avec les vrais composants : qui est le client, où vit votre serveur, où sont stockés les identifiants Google Cloud. Repérez l’étape où une fuite serait possible si l’on sautait le serveur.

Lire un stop_reason. Écrivez une petite fonction verifier(message) qui lève une exception si stop_reason vaut max_tokens ou refusal, et renvoie le texte sinon. Elle vous servira dans tout le cours.

Sources officielles : Accessing the API (Claude Academy, Claude on Google Cloud) · Create a Message (référence de l’API : paramètres, blocs de réponse, valeurs de stop_reason) · Claude Models on Google Cloud (Google managed) (documentation Claude : Vertex AI)

Points clés à retenir

Cinq étapes : client, votre serveur, Vertex AI, traitement par le modèle, réponse ; les identifiants ne quittent jamais le serveur.
Trois paramètres obligatoires : model, max_tokens, messages, plus des identifiants Google Cloud qui authentifient.
En interne : tokenisation, embeddings, contextualisation, génération token par token ; les modèles actuels peuvent réfléchir avant de répondre.
stop_reason dit pourquoi la génération s’est arrêtée ; votre code le vérifie avant d’utiliser une réponse.
content est une liste de blocs : on lit les blocs text, jamais content[0] à l’aveugle.