# D1 · Applications and Integration
Approfondissement de la Messages API – anatomie requête/réponse, streaming, thinking, prompt caching, traitement par batch, erreurs, limites de débit, SDK, accès tiers, fondamentaux du génie logiciel, conception d’application et gestion de la configuration.
import { Accordions, AccordionItem, Tabs, TabItem, Steps } from '@prosefly/astro-components';
C’est de loin le domaine le plus lourd de l’examen Developer – environ **18 items sur 53**. Il vérifie que vous savez intégrer Claude *correctement* : connaître la forme exacte d’une requête et d’une réponse de la Messages API, gérer chaque `stop_reason`, streamer avec SSE, utiliser des entrées vision/PDF/Files, câbler le prompt caching et le traitement par batch pour le coût, traiter les erreurs et les limites de débit, et structurer une application pour que les instructions, la configuration et les secrets se trouvent au bon endroit. La plupart des items sont des scénarios en forme de code où une option est subtilement fausse sur un mécanisme de l’API.
## Objectifs d’apprentissage
À la fin de cette page, vous devriez être capable de :
1. Décrire l’**anatomie d’une requête et d’une réponse de la Messages API**, y compris les rôles, les blocs de contenu, `system`, `max_tokens`, `temperature`/`top_p`, `stop_sequences` et `usage`.
2. Gérer chaque valeur de **`stop_reason`**, y compris `tool_use`, `pause_turn`, `refusal` et `max_tokens`.
3. Maintenir correctement un **historique multi-tours** et streamer les réponses à l’aide des **types d’événements SSE** en Python et TypeScript.
4. Envoyer des entrées **vision, PDF et Files API**, et activer le **thinking étendu / adaptatif**.
5. Appliquer le **prompt caching** avec `cache_control` et calculer son impact sur le coût.
6. Utiliser le cycle de vie de la **Message Batches API** et sa remise de 50 %.
7. Gérer les **codes d’erreur**, mettre en œuvre un **retry avec backoff + jitter**, utiliser l’**idempotence**, et raisonner sur les **limites de débit** (RPM/ITPM/OTPM) et les **timeouts**.
8. Accéder à Claude via **Bedrock, Vertex AI et Foundry**, et utiliser les **SDK Python et TypeScript**, y compris les patterns asynchrones.
9. Appliquer les **fondamentaux du génie logiciel** (REST, JSON, asynchrone, gestion de versions, refactorisation) et une **conception d’application** et une **gestion de la configuration** saines.
---
## 1.1 Requirements and the application lifecycle
Avant tout code, une intégration a un cycle de vie : **définir les besoins → prototyper → évaluer → durcir → déployer → superviser → itérer.** L’examen attend de vous que vous sachiez où Claude s’insère et ce qui change à chaque étape.
| Stage | Key decisions | Claude-specific concerns |
| --- | --- | --- |
| Requirements | Tâche, niveau de qualité, budget de latence, plafond de coût, sensibilité des données | Quel palier de modèle ; sync vs batch ; besoins ZDR |
| Prototype | Prompt du chemin nominal, modèle, forme de sortie | Épingler un snapshot ; capturer des exemples d’entrées/sorties |
| Evaluate | Jeu de référence, métriques, précision par segment | LLM-as-judge dans une session *séparée* ; température 0 pour la reproductibilité |
| Harden | Erreurs, retries, timeouts, limites de débit, validation | Backoff + jitter ; validation-retry de schéma ; hooks pour les règles critiques |
| Deploy | Secrets, config, observabilité | Clés dans un gestionnaire de secrets ; journaliser les request ID ; épingler la version du modèle |
| Monitor / iterate | Dérive, coût, latence, échecs | Suivre `usage`, le taux de cache hit, la distribution des `stop_reason` |
:::tip[Signal d’examen]
Des mots comme « avant la production », « fiabilité », « reproductible », « plafond de coût » ou « SLA » vous orientent vers des préoccupations de durcissement – retries, timeouts, épinglage, validation – et non vers la formulation du prompt.
:::
---
## 1.2 Anatomy of a Messages API request
Une requête Messages est un corps JSON envoyé à `POST /v1/messages`. Les champs principaux :
```json
{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"system": "You are a precise assistant. Answer only from the provided context.",
"messages": [
{ "role": "user", "content": "Summarise the attached report in 3 bullets." }
],
"temperature": 0.2,
"stop_sequences": ["\n\nHuman:"]
}
```
Champs clés :
- **`model`** – un ID de modèle ; épinglez un snapshot en production (voir 1.16).
- **`max_tokens`** – le nombre maximal de tokens que Claude peut *générer* (et non la fenêtre de contexte). Obligatoire. Si la sortie l’atteint, `stop_reason` vaut `max_tokens`.
- **`system`** – une chaîne de premier niveau (ou un tableau de blocs) pour le rôle/les instructions. Ce n’est **pas** un message avec `role: "system"` dans le tableau `messages` sur les modèles actuels (Sonnet 5 n’a pas de messages système en milieu de conversation).
- **`messages`** – une liste alternant les tours `user` et `assistant`. Chacun a un `role` et un `content`.
- **`temperature`** (0–1) et **`top_p`** – contrôles d’échantillonnage. Réglez-en **un**, pas les deux. Une température plus basse = plus déterministe ; `temperature: 0` pour une reproductibilité maximale.
- **`stop_sequences`** – des chaînes qui, si elles sont générées, arrêtent la sortie ; `stop_reason` devient alors `stop_sequence`.
### Roles and content blocks
`content` est soit une chaîne (raccourci pour un unique bloc texte), soit un **tableau de blocs de contenu**. Les types de blocs incluent `text`, `image`, `document`, `tool_use`, `tool_result` et `thinking`.
```json
{
"role": "user",
"content": [
{ "type": "text", "text": "What is in this image?" },
{ "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KG..." } }
]
}
```
:::note[Les rôles sont stricts]
`messages` doit commencer par `user` et alterner. Les réponses antérieures de l’assistant (y compris les blocs `tool_use`) sont renvoyées telles quelles en `role: "assistant"` ; les sorties d’outils reviennent en `role: "user"` avec des blocs `tool_result`. Se tromper de rôle est une erreur `400 invalid_request` courante.
:::
---
## 1.3 Anatomy of a Messages API response
```json
{
"id": "msg_01ABC...",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-5",
"content": [
{ "type": "text", "text": "Here are three bullets: ..." }
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 2145,
"output_tokens": 87,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}
```
- **`id`** – journalisez-le (ainsi que l’en-tête de réponse `request-id`) pour le support et le débogage.
- **`content`** – tableau de blocs de sortie ; itérez plutôt que de supposer un unique bloc texte (une réponse peut contenir ensemble des blocs `thinking`, `text` et `tool_use`).
- **`stop_reason`** – la raison de l’arrêt de la génération (voir 1.4).
- **`usage`** – comptabilité des tokens, y compris les champs de cache. Facturez et budgétez à partir de là.
:::tip[Signal d’examen]
Si une option suppose que `response.content[0].text` existe toujours, méfiez-vous. Avec le thinking ou les outils activés, `content[0]` peut être un bloc `thinking` ou `tool_use`. Un code correct itère et filtre par `type`.
:::
---
## 1.4 `stop_reason` – the control signal
`stop_reason` est le champ le plus important pour le flux de contrôle. Ne déduisez jamais la fin à partir du texte.
| `stop_reason` | Meaning | Correct handling |
| --- | --- | --- |
| `end_turn` | Claude a terminé naturellement | Renvoyer la réponse |
| `tool_use` | Claude veut exécuter un outil | Exécuter le(s) outil(s), ajouter `tool_result`, rappeler |
| `max_tokens` | Plafond `max_tokens` atteint | La sortie est tronquée ; augmenter le plafond ou continuer, ne pas traiter comme terminée |
| `stop_sequence` | Chaîne `stop_sequences` atteinte | Vérifier le champ `stop_sequence` pour savoir laquelle |
| `pause_turn` | Tour de longue durée mis en pause (p. ex. outils serveur) | Renvoyer la réponse inchangée pour reprendre |
| `refusal` | Claude a décliné pour des raisons de sécurité | Ne pas réessayer aveuglément ; remonter/traiter selon la politique |
```python
resp = client.messages.create(model="claude-sonnet-5", max_tokens=1024, messages=msgs)
if resp.stop_reason == "tool_use":
handle_tools(resp) # exécuter, ajouter tool_result, boucler
elif resp.stop_reason == "pause_turn":
msgs.append({"role": "assistant", "content": resp.content})
resp = client.messages.create(model="claude-sonnet-5", max_tokens=1024, messages=msgs)
elif resp.stop_reason == "max_tokens":
handle_truncation(resp) # la sortie est incomplète
elif resp.stop_reason == "refusal":
handle_refusal(resp) # chemin de politique, pas une boucle de retry
```
:::danger[Anti-pattern nº 1]
Analyser la prose de l’assistant (« On dirait que j’ai terminé », « Je vais m’arrêter maintenant ») pour décider de s’arrêter est l’anti-pattern nº 1. Pilotez la boucle à partir de `stop_reason`.
:::
---
## 1.5 Multi-turn conversations
L’état est côté client : vous renvoyez tout l’historique à chaque tour. Ajoutez la réponse de l’assistant telle quelle, puis le tour suivant de l’utilisateur.
```python
messages = [{"role": "user", "content": "My name is Dana."}]
r1 = client.messages.create(model="claude-sonnet-5", max_tokens=256, messages=messages)
messages.append({"role": "assistant", "content": r1.content}) # ajouter les blocs complets
messages.append({"role": "user", "content": "What is my name?"})
r2 = client.messages.create(model="claude-sonnet-5", max_tokens=256, messages=messages)
```
Comme l’historique grandit à chaque tour, le coût d’entrée et la latence augmentent aussi. C’est pourquoi le **prompt caching** (1.9), l’**édition de contexte** et la **compaction** comptent pour les conversations longues.
:::caution[Fable 5.1 est append-only]
Sur `claude-fable-5-1`, éditer, réordonner ou supprimer des tours antérieurs invalide les blocs `thinking` ultérieurs. Les harnais doivent être **append-only** : figez `system` et `tools`, placez les modifications en cours de session dans des messages `role: "system"` là où c’est pris en charge, et élaguez côté serveur via l’édition de contexte / la compaction plutôt qu’en mutant l’historique.
:::
---
## 1.6 Streaming with SSE
Le streaming renvoie des Server-Sent Events pour que vous puissiez afficher les tokens à mesure qu’ils arrivent. La séquence d’événements :
```text
message_start
content_block_start (index 0)
content_block_delta ... (text_delta / input_json_delta / thinking_delta)
content_block_stop
[more content blocks ...]
message_delta (carries stop_reason and final usage)
message_stop
```
```python
from anthropic import Anthropic
client = Anthropic()
with client.messages.stream(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Write a haiku about tokens."}],
) as stream:
for text in stream.text_stream: # pratique : deltas de texte uniquement
print(text, end="", flush=True)
final = stream.get_final_message() # Message complet avec stop_reason + usage
print("\n", final.stop_reason, final.usage.output_tokens)
```
```typescript
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
const stream = client.messages.stream({
model: 'claude-sonnet-5',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Write a haiku about tokens.' }],
});
stream.on('text', (delta) => process.stdout.write(delta));
const final = await stream.finalMessage();
console.log('\n', final.stop_reason, final.usage.output_tokens);
```
```python
with client.messages.stream(model="claude-sonnet-5", max_tokens=512,
messages=[{"role": "user", "content": "hi"}]) as stream:
for event in stream:
if event.type == "content_block_delta":
if event.delta.type == "text_delta":
print(event.delta.text, end="")
elif event.delta.type == "input_json_delta":
print(event.delta.partial_json, end="") # les args d'outil arrivent en JSON
elif event.type == "message_delta":
print("\nstop:", event.delta.stop_reason)
```
:::tip[Signal d’examen]
« Afficher la sortie au fur et à mesure de sa génération », « améliorer la latence perçue », « réponse longue » → streaming. Rappelez-vous que les arguments d’outil arrivent en `input_json_delta` (JSON partiel) et que le `stop_reason`/`usage` final arrive sur `message_delta`.
:::
---
## 1.7 Vision, PDF and the Files API
Les entrées multimodales sont des blocs de contenu dans un message `user`.
```json
{
"role": "user",
"content": [
{ "type": "text", "text": "Extract the invoice total." },
{ "type": "image", "source": { "type": "url", "url": "https://example.com/invoice.png" } },
{ "type": "document", "source": { "type": "base64", "media_type": "application/pdf", "data": "JVBERi0..." } }
]
}
```
- **Images** : `source.type` peut être `base64` ou `url`. Les types pris en charge incluent PNG, JPEG, GIF, WebP.
- **PDF** : `type: "document"` avec `application/pdf` ; Claude lit le texte et les images des pages.
- **Files API** : téléversez une fois les fichiers volumineux ou réutilisés, puis référencez-les par `file_id` au lieu de renvoyer les octets à chaque tour – économise la bande passante de téléversement et permet la réutilisation.
```python
uploaded = client.files.upload(file=("report.pdf", open("report.pdf", "rb"), "application/pdf"))
resp = client.messages.create(
model="claude-sonnet-5", max_tokens=1024,
messages=[{"role": "user", "content": [
{"type": "text", "text": "Summarise."},
{"type": "document", "source": {"type": "file", "file_id": uploaded.id}},
]}],
)
```
Les **citations** peuvent être activées sur les documents pour que Claude renvoie des références ancrées vers des passages de la source.
---
## 1.8 Extended and adaptive thinking
Le thinking permet à Claude de raisonner avant de répondre ; le raisonnement apparaît sous forme de blocs de contenu `thinking`.
```json
{
"model": "claude-opus-5",
"max_tokens": 4096,
"thinking": { "type": "adaptive" },
"messages": [{ "role": "user", "content": "Prove sqrt(2) is irrational." }]
}
```
- **Tous les modèles actuels** acceptent `thinking: {"type": "adaptive"}`.
- **`budget_tokens`** n’est valide que sur **Haiku 4.5** ; il renvoie `400` sur Fable 5.x / Opus 5 / Sonnet 5.
- Les **niveaux d’effort** `low | medium | high (default) | xhigh` ajustent la profondeur de raisonnement (`xhigh` pour les travaux de code/agentiques les plus ardus sur Opus 5 / Fable 5.1). Haiku 4.5 n’a pas de paramètre `effort`.
- **Fable 5.1** a toujours le thinking activé ; ses blocs de thinking ne sont lisibles que par le modèle producteur ou plus récent (un repli silencieux vers un modèle plus ancien les supprime).
```python
# Haiku 4.5 – le seul modèle actuel utilisant budget_tokens
client.messages.create(
model="claude-haiku-4-5", max_tokens=2048,
thinking={"type": "enabled", "budget_tokens": 1024},
messages=[{"role": "user", "content": "Plan the refactor."}],
)
```
:::caution[Préservez les blocs de thinking]
Lorsque vous poursuivez une conversation ayant utilisé le thinking, renvoyez les blocs `thinking` de l’assistant tels quels. Les supprimer peut casser les continuations d’utilisation d’outils et, sur Fable 5.1, invalider les tours ultérieurs.
:::
---
## 1.9 Prompt caching mechanics and cost math
Le prompt caching stocke un préfixe de la requête pour que les appels répétés évitent de le retraiter. Marquez la **fin** du préfixe stable avec `cache_control`.
```json
{
"model": "claude-sonnet-5",
"max_tokens": 512,
"system": [
{ "type": "text", "text": "You are a support agent. Policies:\n...large...",
"cache_control": { "type": "ephemeral" } }
],
"messages": [{ "role": "user", "content": "How do I return an item?" }]
}
```
Règles :
- Placez le **contenu stable en premier** (prompt système, définitions d’outils, longs documents), puis le contenu variable.
- Le préfixe minimal pouvant être mis en cache est d’**environ 1024 tokens** (2048 sur Haiku).
- Une **écriture de cache** coûte ≈ **1,25×** l’entrée de base (TTL de 5 minutes) ou **2×** (TTL d’1 heure).
- Une **lecture de cache** coûte ≈ **0,1×** l’entrée de base (10 % du prix).
- Rapporté dans `usage` sous `cache_creation_input_tokens` et `cache_read_input_tokens`.
### Worked cost example
Un bot de support envoie un préfixe de politique mis en cache de 10 000 tokens sur Sonnet 5 (entrée $2/MTok) plus 200 tokens variables, à 100 appels/heure.
| Scenario | Prefix cost per call | Notes |
| --- | --- | --- |
| No caching | 10 000 × $2 / 1e6 = **$0.0200** | Retraité à chaque appel |
| First call (write, 5-min) | 10 000 × $2 × 1.25 / 1e6 = **$0.0250** | Payé une fois |
| Cache hits (reads) | 10 000 × $2 × 0.1 / 1e6 = **$0.0020** | 90 % moins cher sur le préfixe |
Sur 100 appels : sans cache ≈ **$2.00** sur le préfixe ; avec cache ≈ $0.025 + 99 × $0.002 ≈ **$0.223** – soit une réduction d’environ **9×** sur la portion mise en cache.
:::tip[Signal d’examen]
« Mêmes instructions/documents volumineux à chaque appel », « réduire le coût d’entrée », « fort volume de requêtes avec un préfixe partagé » → prompt caching. Si le préfixe change à chaque appel, le caching n’aide pas.
:::
---
## 1.10 Message Batches API
Pour un travail à fort volume tolérant à la latence, la Batches API traite de nombreuses requêtes de manière asynchrone avec une **remise de 50 %** sur les tokens d’entrée et de sortie, avec des résultats généralement bien en deçà de 24 heures.
1. **Créez** un batch avec une liste de requêtes, chacune ayant un `custom_id`.
```python
batch = client.messages.batches.create(requests=[
{"custom_id": "row-1", "params": {"model": "claude-haiku-4-5", "max_tokens": 256,
"messages": [{"role": "user", "content": "Classify: great product"}]}},
{"custom_id": "row-2", "params": {"model": "claude-haiku-4-5", "max_tokens": 256,
"messages": [{"role": "user", "content": "Classify: terrible support"}]}},
])
```
2. **Interrogez** `processing_status` jusqu’à ce qu’il soit `ended`.
```python
import time
while client.messages.batches.retrieve(batch.id).processing_status != "ended":
time.sleep(30)
```
3. **Streamez les résultats** et faites la correspondance par `custom_id`.
```python
for result in client.messages.batches.results(batch.id):
print(result.custom_id, result.result.type) # "succeeded" | "errored" | "expired"
```
:::tip[Signal d’examen]
« De nuit », « classification nocturne de milliers d’enregistrements », « non sensible à la latence », « diviser le coût par deux » → Message Batches. Si un utilisateur attend en temps réel, le batch est le mauvais choix.
:::
---
## 1.11 Error codes, retries and idempotency
| Status | Type | Retry? |
| --- | --- | --- |
| 400 | `invalid_request_error` | Non – corriger la requête |
| 401 | `authentication_error` | Non – corriger la clé |
| 403 | `permission_error` | Non |
| 404 | `not_found_error` | Non |
| 413 | `request_too_large` | Non – réduire la requête |
| 429 | `rate_limit_error` | Oui – backoff, respecter `retry-after` |
| 500 | `api_error` | Oui – backoff |
| 529 | `overloaded_error` | Oui – backoff |
Réessayez `429`, `500` et `529` avec un **backoff exponentiel + jitter** ; ne réessayez pas les `4xx` autres que `429`.
```python
import time, random
from anthropic import Anthropic, APIStatusError, RateLimitError
client = Anthropic(max_retries=0) # désactiver le retry auto du SDK pour montrer le pattern
def call_with_backoff(**kwargs):
for attempt in range(6):
try:
return client.messages.create(**kwargs)
except (RateLimitError, APIStatusError) as e:
status = getattr(e, "status_code", None)
if status not in (429, 500, 529):
raise
retry_after = float(getattr(e, "response", None).headers.get("retry-after", 0)) if getattr(e, "response", None) else 0
sleep = max(retry_after, min(60, (2 ** attempt))) + random.uniform(0, 1) # jitter
time.sleep(sleep)
raise RuntimeError("exhausted retries")
```
Les SDK réessaient sans danger par défaut (`max_retries=2`). Pour l’**idempotence** sur les écritures (p. ex. la création de batch), passez une clé d’idempotence afin qu’une requête réessayée ne soit pas traitée deux fois.
:::note[Journalisez le request ID]
Chaque réponse porte un `request-id`. Journalisez-le avec votre propre ID de corrélation ; le support Anthropic et vos traces s’appuient tous deux dessus. Cela soutient directement le débogage du Domaine 8.
:::
---
## 1.12 Rate limits and timeouts
Les limites de débit sont appliquées par modèle et par palier selon trois axes :
| Limit | Meaning |
| --- | --- |
| **RPM** | Requêtes par minute |
| **ITPM** | Tokens d’entrée par minute |
| **OTPM** | Tokens de sortie par minute |
Vous pouvez atteindre l’une avant les autres. Les réponses `429` portent `retry-after` et des en-têtes de limite de débit. Stratégies : limitation/mise en file d’attente côté client, étalement de la charge, batching, demande d’un palier supérieur, et réduction des tokens (sortie plus courte, caching). Utilisez `client.models.list()` / `.retrieve(id)` pour les limites en direct.
Réglez les **timeouts** délibérément – un thinking long ou de grandes sorties nécessitent des timeouts généreux ; les appels interactifs courts doivent échouer vite. Les SDK exposent une option `timeout`.
```typescript
const client = new Anthropic({ timeout: 60_000, maxRetries: 3 });
```
---
## 1.13 Third-party access: Bedrock, Vertex, Foundry
Claude est disponible via trois plateformes cloud en plus de l’Anthropic API. La forme de la Messages API est identique ; l’authentification, les ID de modèle et la région diffèrent.
| Platform | SDK | Auth | Notes |
| --- | --- | --- | --- |
| Anthropic API | `anthropic` / `@anthropic-ai/sdk` | `ANTHROPIC_API_KEY` | Complet, accès le plus précoce aux fonctionnalités |
| Amazon Bedrock | `AnthropicBedrock` | AWS IAM / SigV4 | FedRAMP High disponible ; ID de modèle Bedrock |
| Google Vertex AI | `AnthropicVertex` | GCP ADC / compte de service | ID de modèle Vertex, restreints par région |
| Microsoft Foundry | Foundry SDK / API | Entra ID | Gouvernance native Azure |
```python
from anthropic import AnthropicBedrock
client = AnthropicBedrock(aws_region="us-east-1")
resp = client.messages.create(model="anthropic.claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Hello"}])
```
:::tip[Signal d’examen]
« Les données doivent rester dans notre compte AWS/GCP/Azure », « FedRAMP », « gouvernance cloud existante » → Bedrock / Vertex / Foundry. Le code diffère surtout par le constructeur du client et les ID de modèle.
:::
---
## 1.14 SDKs and async patterns
```python
from anthropic import Anthropic
client = Anthropic() # lit ANTHROPIC_API_KEY depuis l'environnement
resp = client.messages.create(model="claude-sonnet-5", max_tokens=256,
messages=[{"role": "user", "content": "Hi"}])
print(resp.content[0].text)
```
```python
import asyncio
from anthropic import AsyncAnthropic
client = AsyncAnthropic()
async def classify(text: str) -> str:
r = await client.messages.create(model="claude-haiku-4-5", max_tokens=64,
messages=[{"role": "user", "content": f"Label: {text}"}])
return r.content[0].text
async def main():
results = await asyncio.gather(*[classify(t) for t in ["a", "b", "c"]])
print(results)
asyncio.run(main())
```
```typescript
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
const results = await Promise.all(
['a', 'b', 'c'].map((t) =>
client.messages.create({
model: 'claude-haiku-4-5',
max_tokens: 64,
messages: [{ role: 'user', content: `Label: ${t}` }],
}),
),
);
console.log(results.map((r) => r.content[0].type));
```
Utilisez l’**asynchrone / la concurrence** pour paralléliser les appels indépendants (en respectant les limites de débit), jamais pour simuler un ordre entre appels dépendants. Pour des milliers d’items indépendants qui peuvent attendre, préférez le **batching** à une concurrence artisanale.
---
## 1.15 Software-engineering foundations
L’examen suppose une maîtrise des fondamentaux qui rendent une intégration robuste.
| Foundation | What the exam expects |
| --- | --- |
| **REST** | Claude est une API HTTP JSON : méthodes, codes de statut, en-têtes (`x-api-key`, `anthropic-version`), idempotence |
| **JSON** | Corps de requête/réponse, schémas, échappement ; valider avant de faire confiance |
| **Async** | IO non bloquantes, limites de concurrence, backpressure ; paralléliser les appels indépendants |
| **Version control** | Committer les prompts, schémas et config ; relire les changements ; taguer les versions |
| **Refactoring** | Extraire les templates de prompt, centraliser le client, isoler les ID de modèle pour qu’une migration soit un changement d’une ligne |
:::note[Pourquoi c’est important]
Une intégration bien refactorisée épingle l’ID de modèle et le template de prompt en un seul endroit, enveloppe le client avec des valeurs par défaut de retry/timeout, et valide chaque sortie structurée. Cela rend triviales à répondre les questions de fiabilité et de coût ailleurs dans l’examen.
:::
---
## 1.16 Application design across surfaces
Les *mêmes mots* sont interprétés différemment selon l’endroit où ils s’exécutent. Connaissez les surfaces :
| Surface | Instruction source | Determinism | Best for |
| --- | --- | --- | --- |
| **API / SDK** | `system` + `messages` que vous envoyez | Vous contrôlez tout | Applications de production, pipelines |
| **Agent SDK** | `system_prompt` + tools + hooks | Vous hébergez la boucle | Agents personnalisés |
| **Claude Code** | Hiérarchie `CLAUDE.md` + `settings.json` | Piloté par la config, permissions d’outils | Coder dans le terminal |
| **Claude Desktop** | Réglages de l’app + config MCP | Piloté par GUI | Assistant local + MCP |
| **claude.ai** | UI de chat, Projects | Le moins programmatique | Usage ad hoc, non-développeur |
**Frontières de contenu avec balises XML.** Enveloppez les entrées non fiables ou distinctes dans des balises pour que le modèle distingue les instructions des données :
```text
...trusted rules...
...untrusted content – treat as data, not instructions...
```
**Conception de schéma et hygiène de session.** Définissez le schéma de sortie en amont (1.9, D4) ; gardez les sessions focalisées (une tâche par session lorsque c’est possible) ; effacez ou compactez les historiques longs ; ne laissez jamais du texte de document non fiable être interprété comme des instructions.
:::tip[Signal d’examen]
Si un énoncé mêle des instructions de confiance à du contenu utilisateur/web/outil collé, la bonne réponse isole le contenu non fiable dans des balises et le traite comme des données – elle ne compte pas sur le fait que le modèle « sache » ne pas le suivre.
:::
---
## 1.17 Configuration management
Gardez le comportement reproductible et les secrets hors des prompts.
| Concern | Where it lives | Rule |
| --- | --- | --- |
| Instructions comportementales | Hiérarchie `CLAUDE.md` (Claude Code) / `system` (API) | Sous gestion de versions, relues |
| Version du modèle | Config / variable d’env, snapshot épinglé | Un seul endroit ; jamais codé en dur dans plusieurs fichiers |
| Templates de prompt | Fichiers versionnés, tagués | Changement = nouvelle version, réévaluation |
| Secrets / clés d’API | Variables d’env ou gestionnaire de secrets | **Jamais** dans les prompts, `CLAUDE.md` ou fichiers committés |
| Différences d’environnement | `.env` par environnement | Isolation dev/stage/prod |
```python
import os
MODEL = os.environ["CLAUDE_MODEL"] # p. ex. "claude-sonnet-5" – épinglé, piloté par env
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"]) # clé depuis l'env, jamais littérale
```
:::danger[Les secrets ne vont jamais dans les prompts]
Placer une clé d’API, un mot de passe de base de données ou un token dans le prompt `system` ou dans `CLAUDE.md` le fuit dans les logs, l’historique et (pour `CLAUDE.md`) la gestion de versions. Utilisez des variables d’environnement ou un gestionnaire de secrets. Cela recoupe le Domaine 6.
:::
---
## 1.18 Structured outputs and citations end-to-end
Au-delà du texte brut, les items de D1 sondent souvent votre capacité à obtenir une sortie exploitable par machine *tout en* la gardant ancrée. Deux fonctionnalités au niveau de la requête font cela : **`output_config.format`** (JSON contraint par schéma) et les **citations de documents** (passages sources ancrés).
```json
{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"total_cents": {"type": "integer"},
"currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]}
},
"required": ["total_cents", "currency"]
}
}
},
"messages": [{"role": "user", "content": [
{"type": "document", "source": {"type": "file", "file_id": "file_01ABC"},
"citations": {"enabled": true}},
{"type": "text", "text": "Extract the invoice total."}
]}]
}
```
Une réponse ancrée peut porter des `citations` sur ses blocs de texte référençant les passages sources :
```json
{
"content": [
{"type": "text", "text": "The total is $482.10.",
"citations": [{"type": "page_location", "cited_text": "Total due: $482.10",
"document_index": 0, "start_page_number": 3, "end_page_number": 3}]}
],
"stop_reason": "end_turn"
}
```
| Feature | What it guarantees | What it does *not* do |
| --- | --- | --- |
| `output_config.format` (schéma JSON) | La sortie est conforme à la forme du schéma | Garantir que les *valeurs* sont correctes — validez quand même la sémantique |
| schéma d’outil `strict: true` | L’entrée de l’outil correspond exactement au schéma | Fonctionner avec un `tool_choice` forcé sur Fable 5.1 (cela renvoie 400) |
| `citations` de document | Les blocs de texte référencent les passages sources utilisés | Empêcher l’hallucination si la source elle-même est erronée |
:::tip[Signal d’examen]
« Doit renvoyer du JSON valide selon le schéma » → `output_config.format` (schéma) ou un outil `strict: true`, **plus une validation-retry**. « Doit montrer d’où vient chaque affirmation » → activer les `citations` de document. La conformité au schéma n’est pas la même chose que l’exactitude des valeurs — l’examen récompense la validation des deux.
:::
---
## 1.19 Idempotency, timeouts and the SDK retry contract
Les écritures et les appels longs nécessitent des contrôles de fiabilité explicites. Les SDK réessaient les erreurs transitoires par défaut, mais l’idempotence et les budgets de timeout vous appartiennent.
| Control | Why it matters | How |
| --- | --- | --- |
| **Clé d’idempotence** | Une création réessayée (p. ex. un batch) ne doit pas s’exécuter deux fois | Passer une clé d’idempotence sur les requêtes d’écriture |
| **Timeout** | Un thinking long / une grande sortie a besoin de marge ; les appels interactifs doivent échouer vite | Régler `timeout` par classe d’appel |
| **Retries bornés** | Récupérer de `429`/`5xx`/`529` sans amplifier la charge | `max_retries` du SDK (défaut 2) + jitter |
| **Plafond de concurrence** | Empêche les tempêtes de limite de débit auto-infligées | Sémaphore / file autour du client |
```python
from anthropic import Anthropic
client = Anthropic(max_retries=3, timeout=120) # retries bornés ; timeout généreux pour le batch
batch = client.messages.batches.create(
requests=[...],
extra_headers={"Idempotency-Key": "nightly-2026-09-15"}, # sûr à réessayer, s'exécute une fois
)
```
```typescript
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({ maxRetries: 3 });
const resp = await client.messages.create(
{ model: 'claude-sonnet-5', max_tokens: 8000, messages },
{ timeout: 120_000 }, // sortie longue → timeout plus long ; les appels courts restent rapides
);
```
:::tip[Signal d’examen]
« Une écriture réessayée s’est exécutée deux fois » → **clé d’idempotence**. « Un appel à sortie longue/thinking dépasse le timeout mais le modèle allait bien » → augmenter le **timeout**, ne pas simplement réessayer. « Les retries aggravent le 429 » → plafonner la concurrence et honorer `retry-after`.
:::
---
## 1.20 Common misconceptions
| Misconception | Reality | Why it matters on the exam |
| --- | --- | --- |
| L’API se souvient de la conversation côté serveur | La Messages API est sans état ; vous renvoyez l’historique à chaque tour | Explique pourquoi historique/caching/coût en tokens augmentent, et pourquoi « n’envoyer que le dernier message » est faux |
| `max_tokens` est la fenêtre de contexte | Il plafonne uniquement la *sortie générée*, dans la fenêtre | Distingue la troncature `max_tokens` d’un 413 request-too-large |
| `response.content[0].text` contient toujours la réponse | Avec thinking/outils, le bloc 0 peut être `thinking`/`tool_use` ; itérez par type | Le distracteur en forme de code le plus courant en D1 |
| Toute erreur devrait être réessayée avec backoff | Seuls `429`/`500`/`529` sont transitoires ; les `4xx` (sauf 429) sont déterministes | Réessayer un `400`/`401` boucle indéfiniment et masque le vrai correctif |
| Le streaming rend la génération plus rapide | Il n’améliore que le time-to-first-token ; le temps total est inchangé | Sépare un correctif de latence perçue d’un correctif de latence réelle |
| Le prompt caching aide toute requête répétée | Seul un préfixe identique octet par octet au-dessus du minimum est mis en cache | Un horodatage ou un nom d’utilisateur par requête dans le préfixe tue le cache |
| Bedrock/Vertex nécessitent de réécrire la requête | Seuls le client/l’authentification et l’ID de modèle changent ; le corps est portable | Les questions de migration reposent sur ce qui change réellement |
| Un refus est une erreur à réessayer | `refusal` est un stop_reason de sécurité délibéré ; routez vers la politique | Empêche les boucles de retry aveugle sur les refus de sécurité |
---
## 1.21 Scenario walkthrough: a resilient extraction service
**Scénario.** Vous détenez un service qui extrait des champs structurés de jusqu’à 100 000 PDF téléversés par nuit. Chaque requête envoie un préfixe instruction+schéma de 6 000 tokens (identique à chaque appel) plus un document ; les résultats sont attendus pour 08:00, pas en temps réel. Le jour, un endpoint interactif à faible volume répond à des questions ad hoc sur un même contrat réutilisé de 180 pages. Récemment, le job nocturne a commencé à échouer par intermittence avec des `429` et des `JSONDecodeError` occasionnels, et la finance a signalé un coût trop élevé. Vous devez le rendre fiable et bon marché sans nuire à la qualité d’extraction (Sonnet 5 passe actuellement la barre).
**Trace de raisonnement d’expert.**
1. **Classez chaque charge de travail par tolérance à la latence.** Le job nocturne est tolérant à la latence et en masse → il relève de la **Message Batches API** (50 % de moins, résultats en 24 h), et non d’une concurrence artisanale qui déclenche des tempêtes de `429`. L’endpoint interactif est en temps réel → gardez-le synchrone.
2. **Attaquez le coût avec les bons leviers, dans l’ordre.** Le modèle le moins cher qui passe la barre est déjà choisi (Sonnet 5 — ne *sautez pas* vers Opus 5, sur-dimensionné ici). Ensuite, **mettez en cache le préfixe stable de 6 000 tokens** (le fait tomber à ~10 % sur les hits) et exécutez via **Batches** (50 % de plus). Empiler modèle + cache + batch est la réponse attendue ; n’en choisir qu’un laisse des économies sur la table.
3. **Corrigez les `429` à la source, pas avec des retries plus serrés.** Passer aux Batches supprime l’essentiel de la pression ; là où des appels synchrones subsistent, plafonnez la concurrence et honorez `retry-after`. Réessayer immédiatement (un distracteur tentant) aggrave la limite.
4. **Corrigez le `JSONDecodeError` dans la bonne couche.** C’est un problème de *sortie du modèle/parsing*, pas de transport. Utilisez **`output_config.format` avec un schéma JSON plus une validation-retry** qui réinjecte l’erreur — pas le backoff, qui est pour les erreurs de transport transitoires.
5. **Traitez efficacement le contrat réutilisé.** Téléversez-le une fois via la **Files API** et référencez-le par `file_id` ; renvoyer 180 pages de base64 à chaque appel est le piège bande passante/coût.
6. **Rejetez les alternatives tentantes.** « Tout basculer vers Opus 5 pour la qualité » — aveugle aux contraintes et coûteux. « Faire tourner les clés d’API pour battre le 429 » — les limites sont par compte, pas par clé. « Augmenter `max_tokens` pour corriger les erreurs JSON » — mauvaise couche ; cela traite la troncature, pas le JSON malformé.
**Décision correcte.** Batches API sur Sonnet 5 avec `cache_control` sur le préfixe partagé et des clés d’idempotence à la création du batch ; sortie contrainte par schéma avec validation-retry pour les erreurs JSON ; Files API pour le contrat réutilisé ; plafonds de concurrence et `retry-after` pour tout appel synchrone restant.
---
## Pièges de l’examen dans ce domaine
| Piège | Pourquoi c’est faux |
| --- | --- |
| Lire `stop_reason` à partir du texte de la réponse | `stop_reason` est un champ structuré ; le texte n’est pas un signal de contrôle (anti-pattern nº 1) |
| Supposer que `response.content[0].text` existe toujours | Avec thinking/outils, `content[0]` peut être un bloc `thinking` ou `tool_use` |
| Régler à la fois `temperature` et `top_p` | Réglez un seul contrôle d’échantillonnage, pas les deux |
| Traiter `max_tokens` comme la fenêtre de contexte | `max_tokens` ne plafonne que la sortie *générée* |
| Utiliser `budget_tokens` sur Sonnet 5 / Opus 5 / Fable 5.1 | Renvoie `400` ; seul Haiku 4.5 utilise encore `budget_tokens` |
| Mettre en cache un préfixe qui change à chaque appel | Aucun cache hit ; le caching n’aide que les préfixes stables |
| Réessayer un `400`/`401` avec backoff | Seuls `429`/`5xx`/`529` sont réessayables |
| Ignorer `retry-after` sur un `429` | Vous continuerez à atteindre la limite ; honorez l’en-tête |
| Placer une clé d’API dans le prompt `system` ou `CLAUDE.md` | Fuit le secret dans les logs/l’historique/le VCS |
| Muter les tours antérieurs sur Fable 5.1 | Invalide les blocs de thinking ultérieurs ; le harnais doit être append-only |
| Utiliser des appels synchrones pour un job en masse nocturne | La Batches API donne 50 % de moins pour un travail tolérant à la latence |
| Envoyer les octets PDF à chaque tour au lieu de la Files API | Gaspille la bande passante ; téléversez une fois et référencez par `file_id` |
| Traiter un JSON conforme au schéma comme automatiquement correct | `output_config.format` garantit la forme, pas les valeurs ; validez aussi la sémantique |
| Réessayer un `refusal` avec backoff | C’est un stop_reason de sécurité délibéré ; routez vers la politique, ne bouclez pas |
| Faire tourner les clés d’API pour battre un `429` | Les limites de débit sont par compte, pas par clé ; plafonnez la concurrence et honorez `retry-after` |
| Augmenter `max_tokens` pour corriger un `JSONDecodeError` | Mauvaise couche ; le JSON malformé est un problème de parsing/sortie du modèle — utilisez schéma + validation-retry |
| Oublier une clé d’idempotence sur une création de batch réessayée | La création peut s’exécuter deux fois ; passez une clé d’idempotence sur les écritures |
---
## Questions d’entraînement
Chaque item indique combien de réponses sélectionner. Essayez avant de révéler.
A. Ajouter une liste de mots-clés (« done », « finished », « complete ») pour attraper plus de cas.
B. Plafonner la boucle à 10 itérations et renvoyer ce qui est présent.
C. Piloter la boucle à partir de `stop_reason` : continuer tant qu’il vaut `tool_use`, s’arrêter sur `end_turn`.
D. Baisser `temperature` pour que la formulation soit cohérente.
**Réponse : C.** La terminaison doit venir du champ structuré `stop_reason` (anti-pattern nº 1). La correspondance de mots-clés (A) est fragile ; les plafonds d’itérations (B) sont l’anti-pattern nº 2 et masquent un travail incomplet ; la température (D) ne crée pas de signal fiable.
A. Le thinking est désactivé par défaut, donc activez-le.
B. `content[0]` est un bloc `thinking` ; itérez `content` et sélectionnez les blocs où `type == 'text'`.
C. Régler `max_tokens` plus haut.
D. Utiliser le streaming à la place.
**Réponse : B.** Avec le thinking ou les outils, le tableau de contenu peut commencer par un bloc `thinking` ou `tool_use`. Un code robuste itère et filtre par type. Les autres ne traitent pas la forme de la réponse.
A. Placer la politique en premier et marquer la fin avec `cache_control: {type: 'ephemeral'}`.
B. Passer `temperature` à 0.
C. Déplacer la politique après la question utilisateur.
D. Réutiliser le préfixe mis en cache entre les requêtes dans le TTL.
E. Augmenter `max_tokens`.
**Réponse : A et D.** Mettre en cache un grand préfixe stable et le réutiliser sur les appels suivants réduit le coût du préfixe à ~10 %. Le préfixe doit venir en premier (C est faux). La température (B) et `max_tokens` (E) n’affectent pas le caching d’entrée.
A. Envoyer 50 000 requêtes synchrones avec une forte concurrence sur Opus 5.
B. Utiliser la Message Batches API sur Haiku 4.5 pour la remise de 50 %.
C. Utiliser le streaming pour accélérer chaque requête.
D. Augmenter le palier de limite de débit et boucler en synchrone.
**Réponse : B.** Le travail en masse tolérant à la latence est le cas d’école des Batches : 50 % de moins, résultats bien en deçà de 24 h, et Haiku 4.5 est le palier le moins cher pour une classification simple. Le streaming (C) ne réduit pas le coût ; le brute-force synchrone (A, D) est coûteux et limité en débit.
A. Réessayer immédiatement dans une boucle serrée jusqu’au succès.
B. Traiter le 429 comme fatal et abandonner la requête.
C. Réessayer avec un backoff exponentiel et du jitter, en honorant l’en-tête `retry-after`.
D. Passer à une autre clé d’API.
**Réponse : C.** Le 429 est réessayable mais uniquement avec backoff + jitter et en respectant `retry-after`. Le retry serré (A) aggrave la limite ; abandonner (B) perd le travail ; faire tourner les clés (D) n’augmente pas la limite du compte et peut violer les conditions.
A. 400 invalid_request
B. 429 rate_limit
C. 401 authentication
D. 529 overloaded
E. 404 not_found
**Réponse : B et D.** Rate-limit et overloaded (et 500) sont transitoires et réessayables avec backoff. 400/401/404 sont des erreurs client que réessayer ne corrigera pas.
A. `budget_tokens` doit être inférieur à 1024.
B. Sonnet 5 n’accepte pas `budget_tokens` ; il n’est valide que sur Haiku 4.5. Utilisez `thinking: {type: 'adaptive'}`.
C. Le thinking n’est pas pris en charge sur Sonnet 5.
D. `max_tokens` doit dépasser `budget_tokens`.
**Réponse : B.** `budget_tokens` a été retiré sur les modèles actuels non-Haiku ; seul Haiku 4.5 l’utilise encore. Les modèles actuels utilisent `thinking: {type: 'adaptive'}` (éventuellement avec des niveaux d’effort). Le thinking est pris en charge sur Sonnet 5 (C faux).
A. Le modèle a terminé ; renvoyer le texte.
B. La sortie a été tronquée au plafond `max_tokens` ; la traiter comme incomplète et augmenter le plafond ou continuer le tour.
C. Le prompt était trop long ; réduire l’entrée.
D. Claude a refusé ; aller au chemin de refus.
**Réponse : B.** `max_tokens` signifie que la génération a été coupée au plafond de sortie ; la réponse est incomplète. `end_turn` (A) signifierait terminé ; la taille d’entrée (C) déclenche un 413 ; le refus (D) est un `stop_reason` différent.
A. Anthropic API avec une clé d’API stockée dans AWS Secrets Manager.
B. Amazon Bedrock avec le client `AnthropicBedrock` et l’auth IAM.
C. Google Vertex AI.
D. claude.ai avec SSO.
**Réponse : B.** Bedrock garde l’inférence dans le compte AWS du client sous IAM/SigV4 et offre FedRAMP High. Stocker une clé Anthropic dans Secrets Manager (A) appelle toujours l’Anthropic API externe. Vertex (C) est GCP ; claude.ai (D) n’est pas un chemin programmatique intra-compte.
A. Coller le texte du PDF dans chaque prompt.
B. Envoyer les octets base64 du PDF à chaque requête.
C. Téléverser une fois via la Files API et le référencer par `file_id` dans chaque requête.
D. Convertir chaque page en image et envoyer les images à chaque fois.
**Réponse : C.** La Files API téléverse une fois et référence par `file_id`, évitant les téléversements répétés. Renvoyer le texte (A), les octets (B) ou les images (D) à chaque fois gaspille bande passante et tokens.
A. Arguments dans `text_delta` ; `stop_reason` dans `message_start`.
B. Arguments dans `input_json_delta` (JSON partiel sur le bloc `tool_use`) ; `stop_reason` dans `message_delta`.
C. Les deux dans `content_block_start`.
D. Les deux seulement après `message_stop`.
**Réponse : B.** Les arguments d’outil sont streamés en JSON partiel `input_json_delta` ; le `stop_reason` final et l’usage arrivent sur `message_delta`, avant `message_stop`.
A. Lire l’ID de modèle depuis une unique constante pilotée par env utilisée partout.
B. Déplacer la clé d’API vers une variable d’environnement / un gestionnaire de secrets et hors du prompt.
C. Stocker la clé d’API dans `CLAUDE.md` pour qu’elle soit documentée.
D. Dupliquer l’ID de modèle dans chaque fichier pour la localité.
E. Committer le fichier `.env` avec la vraie clé pour la reproductibilité.
**Réponse : A et B.** Centralisez l’ID de modèle épinglé (migrations d’une ligne) et gardez les secrets en env/gestionnaire de secrets, jamais dans les prompts. Mettre les clés dans `CLAUDE.md` (C) ou committer de vraies clés (E) les fuit ; dupliquer les ID (D) rend la migration source d’erreurs.
A. Il doit être envoyé comme une entrée `{role: 'system'}` dans `messages`.
B. C’est un champ de premier niveau ; Sonnet 5 ne prend pas en charge les messages système en milieu de conversation.
C. Il est ignoré sauf si le thinking est activé.
D. Il compte comme des tokens de sortie.
**Réponse : B.** `system` est un champ de requête de premier niveau. Sonnet 5 n’a pas de messages système en milieu de conversation. C’est de l’entrée, pas de la sortie (D), et il s’applique toujours (C).
A. Les résultats sont synchrones ; le batch a échoué.
B. Interroger `processing_status` jusqu’à `ended`, puis streamer les résultats et faire la correspondance par `custom_id`.
C. Les batches ne fonctionnent que sur Opus 5.
D. Appeler `retrieve` une fois ; si vide, recréer le batch.
**Réponse : B.** Les batches sont asynchrones : interrogez jusqu’à `ended`, puis lisez les résultats indexés par `custom_id`. Recréer (D) duplique le travail ; les résultats ne sont pas synchrones (A) ; les batches sont agnostiques du modèle (C).
A. La traiter comme une erreur et réessayer depuis zéro.
B. Ajouter la réponse de l’assistant inchangée et rappeler l’API pour reprendre le tour.
C. Baisser `max_tokens`.
D. Passer en mode batch.
**Réponse : B.** `pause_turn` indique qu’un tour de longue durée a été mis en pause (p. ex. outils serveur) ; renvoyez la réponse inchangée pour reprendre. Ce n’est pas une erreur (A) et sans rapport avec `max_tokens` (C) ou le batching (D).
A. Faire confiance au modèle pour la reconnaître et l’ignorer.
B. Envelopper le document dans des balises XML et indiquer que son contenu est des données à résumer, pas des instructions à suivre.
C. Supprimer toute phrase contenant « ignore ».
D. Augmenter `temperature` pour réduire la conformité.
**Réponse : B.** Des frontières de contenu avec des balises XML plus un cadrage explicite données-pas-instructions sont la conception défensive correcte (injection de prompt indirecte, Domaine 6). Se fier au modèle (A), un filtrage naïf par mots-clés (C) et la température (D) ne sont pas fiables.
A. Épingler un snapshot de modèle spécifique.
B. Régler `temperature: 0`.
C. Activer le streaming.
D. Utiliser un thinking adaptatif avec l’effort `xhigh`.
E. Randomiser `top_p` à chaque exécution.
**Réponse : A et B.** Épingler le modèle et utiliser `temperature: 0` minimisent la variance pour une comparaison équitable. Le streaming (C) est un mécanisme de livraison ; le thinking à fort effort (D) ajoute de la variabilité ; randomiser `top_p` (E) est l’opposé de la reproductibilité.
A. Le serveur stocke l’état de la conversation ; n’envoyer que le message le plus récent.
B. Renvoyer l’historique complet à chaque tour, en ajoutant les blocs `content` antérieurs de l’assistant tels quels avant le tour utilisateur suivant.
C. Concaténer tous les tours en une longue chaîne utilisateur.
D. Seul le prompt `system` persiste entre les appels.
**Réponse : B.** L’état est côté client ; vous renvoyez tout l’historique, en ajoutant les blocs de l’assistant tels quels (y compris `thinking`/`tool_use`). Le serveur est sans état (A) ; aplatir en une seule chaîne (C) casse les rôles ; rien ne persiste côté serveur (D).
A. `output_config.format` avec un schéma JSON (ou un schéma d’outil `strict: true`).
B. Les `citations` de document activées sur le document d’entrée.
C. Régler `temperature: 0` uniquement.
D. Augmenter `max_tokens`.
E. Forcer un outil via `tool_choice` sur Fable 5.1.
**Réponse : A et B.** La sortie contrainte par schéma garantit la forme, et les citations de document renvoient les passages sources utilisés. La température (C) et `max_tokens` (D) n’affectent ni la forme ni l’ancrage ; forcer un outil sur Fable 5.1 (E) renvoie 400.
A. Baisser `max_tokens`.
B. Passer une clé d’idempotence sur la requête de création de batch pour qu’un retry soit dédupliqué.
C. Passer à des appels synchrones.
D. Ajouter davantage de backoff exponentiel.
**Réponse : B.** Une clé d’idempotence rend la création sûre à réessayer — elle s’exécute une fois. `max_tokens` (A) est sans rapport ; les appels synchrones (C) perdent la remise batch et ne déduplifient pas ; plus de backoff (D) n’empêche pas une création dupliquée.
A. Rembourrer le préfixe à 16k tokens.
B. Déplacer l’horodatage hors du préfixe mis en cache (après le point de rupture du cache) pour que le préfixe soit identique octet par octet entre les appels.
C. Augmenter le TTL du cache à 1 heure.
D. Désactiver le caching ; il n’aide pas ici.
**Réponse : B.** Tout changement d’octet dans le préfixe défait le caching ; déplacer l’horodatage par requête après le point de rupture rétablit les hits. Le rembourrage (A) ne corrige pas un préfixe changeant ; un TTL plus long (C) exige toujours des octets identiques ; désactiver (D) renonce à une économie réelle une fois le préfixe stabilisé.
A. Envoyer plus de requêtes par minute puisque le RPM va bien.
B. Réduire les tokens d’entrée par requête (mettre en cache le préfixe partagé, élaguer le contexte) et/ou demander un palier supérieur.
C. Augmenter `max_tokens` pour avoir besoin de moins de requêtes.
D. Baisser `temperature` pour réduire l’usage de tokens.
**Réponse : B.** L’axe contraignant est les tokens d’entrée par minute, donc réduisez les tokens d’entrée ou montez de palier. Envoyer plus de RPM (A) ignore l’axe contraignant ; augmenter `max_tokens` (C) accroît les tokens de SORTIE ; la température (D) ne change pas le nombre de tokens.
A. Le constructeur du client et l’authentification (`AnthropicBedrock`, AWS IAM/SigV4).
B. Le format de l’ID de modèle (identifiants de type Bedrock).
C. La signification des valeurs de `stop_reason`.
D. Le fait que `max_tokens` soit requis.
E. La forme de base de `messages`/`system`.
**Réponse : A et B.** Seuls le client/l’authentification et le format de l’ID de modèle changent ; le corps de la requête et la sémantique des champs de contrôle sont portables. La signification de `stop_reason` (C), l’exigence de `max_tokens` (D) et la forme de `messages`/`system` (E) sont inchangées.
A. Un nouveau client synchrone par requête dans la boucle d’événements, sans timeout.
B. Le client asynchrone avec un `timeout` délibéré, des retries SDK bornés pour les erreurs transitoires, et un plafond de concurrence qui respecte les limites de débit.
C. Désactiver tous les retries et timeouts pour maximiser le débit.
D. Une concurrence illimitée pour que chaque requête parte d’un coup.
**Réponse : B.** Un client asynchrone avec un timeout, des retries bornés et un plafond de concurrence est le pattern robuste. Un client synchrone par requête sans timeout (A) bloque la boucle ; désactiver les filets de sécurité (C) supprime la récupération transitoire ; la concurrence illimitée (D) provoque des tempêtes de 429.
## À retenir
- La Messages API est une API HTTP JSON sans état ; vous renvoyez l’historique à chaque tour et facturez à partir de `usage`.
- Pilotez le flux de contrôle à partir de `stop_reason` – n’analysez jamais la prose, ne comptez jamais sur des plafonds d’itérations.
- `content` est un tableau de blocs typés ; itérez et filtrez, ne supposez pas `content[0].text`.
- Streamez avec SSE ; les args d’outil arrivent en `input_json_delta`, le `stop_reason`/`usage` final sur `message_delta`.
- Le prompt caching (préfixe stable en premier, `cache_control`) réduit le coût d’entrée à ~10 % sur les hits ; les Batches donnent 50 % de moins pour un travail tolérant à la latence.
- Ne réessayez que `429`/`500`/`529` avec backoff exponentiel + jitter, honorez `retry-after`, et journalisez le request ID.
- `budget_tokens` est propre à Haiku 4.5 ; les modèles actuels utilisent `thinking: {type: 'adaptive'}` avec des niveaux d’effort.
- Accédez via Bedrock/Vertex/Foundry quand les données ou la conformité l’exigent ; la forme de la requête est inchangée.
- Gardez les ID de modèle épinglés en un seul endroit, les prompts versionnés, et les secrets en env/gestionnaire de secrets – jamais dans les prompts ou `CLAUDE.md`.
- La sortie contrainte par schéma (`output_config.format` / `strict: true`) garantit la forme, pas les valeurs ; validez la sémantique et activez les citations de document quand l’ancrage doit être traçable.
- La fiabilité est en couches : clés d’idempotence sur les écritures, timeouts délibérés pour les appels longs, retries bornés, et un plafond de concurrence pour éviter les `429` auto-infligés.
- Diagnostiquez par couche — un `JSONDecodeError` est un problème de parsing/sortie du modèle (schéma + validation-retry), un `429` est du transport (backoff + `retry-after`) ; appliquer le mauvais correctif est le piège classique.
- Sur Bedrock/Vertex, le corps de la requête et la sémantique de `stop_reason` sont portables ; seuls le client/l’authentification et le format de l’ID de modèle changent.