Toutes les requêtes Claude n’ont pas besoin d’une réponse immédiate.
Certaines applications doivent traiter :
10 000 documents
50 000 tickets support
100 000 descriptions produit
des milliers de résumés
des classifications nocturnes
Dans ce type de workload, faire des appels synchrones un par un est rarement optimal.
Le module introduit pour cela la Message Batches API.
L’idée est simple :
Regrouper de nombreuses requêtes indépendantes dans un traitement asynchrone lorsque personne n’attend immédiatement la réponse.
Le choix entre requête synchrone et batch dépend donc principalement de la nature du workload.
1. Requête interactive vs traitement offline
Supposons qu’un utilisateur discute avec un chatbot.
Il envoie :
"Pourquoi mon paiement a-t-il échoué ?"
Il attend une réponse immédiatement.
Architecture :
User
↓
Application
↓
Claude
↓
Response
↓
User
C’est un workload :
interactive
real-time
latency-sensitive
Un batch n’est pas adapté.
2. Cas différent : 50 000 tickets
Supposons maintenant que chaque nuit vous deviez classifier :
50 000 support tickets
en :
BILLING
TECHNICAL
ESCALATION
Personne n’attend chaque résultat individuellement.
Le workload est :
offline
high-volume
independent requests
C’est précisément le type de cas où un batch devient intéressant.
3. Le principe de la Message Batches API
Conceptuellement :
Application
↓
Prepare many requests
↓
Submit batch
↓
Anthropic processes requests asynchronously
↓
Batch completes
↓
Application retrieves results
Contrairement à une requête synchrone :
request
→ wait
→ response
le batch suit plutôt :
submit
→ continue other work
→ check/retrieve later
4. Un Batch contient plusieurs requêtes indépendantes
Chaque élément du batch correspond conceptuellement à une requête Claude normale.
Par exemple :
Request A
→ classify ticket A
Request B
→ classify ticket B
Request C
→ classify ticket C
Ces requêtes sont regroupées dans un même traitement.
5. Pourquoi « indépendantes » est important
Le batch convient particulièrement lorsque :
Request B
ne dépend pas du résultat de :
Request A
Par exemple :
Document 1 → summarize
Document 2 → summarize
Document 3 → summarize
Chaque document peut être traité séparément.
6. Mauvais candidat au Batch : Workflow dépendant
Supposons :
Step 1:
Analyze database schema.
Step 2:
Using Step 1 result, generate migration.
Step 3:
Using migration, generate rollback.
Ici :
Step 2 depends on Step 1
Step 3 depends on Step 2
Ce n’est pas simplement un ensemble de requêtes indépendantes.
Il faut orchestrer les dépendances.
7. Batch ≠ Agent
Une Message Batch API ne constitue pas un agent.
Le batch ne décide pas :
what to do next
Il exécute un ensemble de requêtes définies par l’application.
Conceptuellement :
Application decides all requests
↓
Batch processes them
C’est donc un workload déterministe et parallèle, pas une boucle agentique.
8. Exemple : classification de tickets
Supposons :
Ticket 001:
"I was charged twice."
Ticket 002:
"The API returns 401."
Ticket 003:
"I want a refund immediately."
Chaque ticket devient une requête distincte :
001 → Claude
002 → Claude
003 → Claude
mais elles sont soumises ensemble dans un batch.
9. custom_id
Le module insiste sur l’utilisation d’un identifiant permettant de faire correspondre chaque résultat à sa requête.
Par exemple :
custom_id = "ticket-001"
Puis :
custom_id = "ticket-002"
et :
custom_id = "ticket-003"
Le résultat contient l’identifiant correspondant.
10. Pourquoi custom_id est essentiel
Le traitement asynchrone ne garantit pas conceptuellement que les réponses soient simplement consommées comme :
input 1 → output 1
input 2 → output 2
input 3 → output 3
en se fiant uniquement à leur position.
L’application doit pouvoir dire :
this response belongs to ticket-002
Le custom_id sert précisément à maintenir cette correspondance.
11. Exemple d’association
Entrées :
ticket-001
ticket-002
ticket-003
Résultats reçus :
ticket-003 → ESCALATION
ticket-001 → BILLING
ticket-002 → TECHNICAL
L’ordre n’est pas le point important.
L’identifiant permet de reconstituer :
ticket-001 = BILLING
ticket-002 = TECHNICAL
ticket-003 = ESCALATION
12. Ne jamais dépendre uniquement de l’ordre
Anti-pattern :
for i, result in enumerate(results):
database_rows[i]["result"] = result
Cette logique suppose que :
result order = input order
Le module recommande plutôt d’utiliser l’identifiant propre à chaque requête.
Conceptuellement :
results_by_id[result.custom_id] = result
13. Cycle de vie d’un Batch
Le modèle mental est :
Create batch
↓
Processing
↓
Completed
↓
Retrieve results
Le traitement est asynchrone.
L’application ne doit donc pas rester bloquée comme pour une requête interactive.
14. Asynchronous ne signifie pas « sans contrôle »
L’application doit toujours gérer :
batch creation
status
results
errors
mapping
persistence
La Batch API ne remplace pas la logique métier.
Elle change principalement le mode d’exécution.
15. Exemple d’architecture
Nightly job
↓
Load 50,000 tickets
↓
Build requests
↓
Assign custom_id
↓
Submit batch
↓
Store batch identifier
↓
Later retrieve results
↓
Match by custom_id
↓
Store classifications
Cette architecture convient mieux à un workload de masse qu’une boucle interactive.
16. Pourquoi le Batch peut réduire le coût
Le module présente le batch comme une option particulièrement intéressante pour les workloads offline, notamment parce qu’il bénéficie d’un coût en tokens inférieur aux requêtes standard synchrones.
Le raisonnement architectural est donc :
No user waiting
+
large volume
+
independent requests
=
Batch may be preferable
L’économie est obtenue en échange d’une latence plus importante.
17. Le compromis principal
On retrouve :
Lower cost
↔
Higher latency
Pour un chatbot :
latency matters
Pour une classification nocturne :
cost and throughput may matter more
La bonne solution dépend donc du workload.
18. Le critère n’est pas seulement le volume
Supposons :
1000 requests
Mais chacune correspond à un utilisateur qui attend une réponse sur une interface.
Même avec un volume élevé :
interactive workload
Le batch reste probablement inadapté.
À l’inverse :
500 offline reports
peut déjà être un bon candidat.
19. Temps réel vs Offline
La distinction importante est :
| Besoin | Approche |
|---|---|
| utilisateur attend maintenant | requête synchrone / streaming |
| traitement différable | batch |
| réponse progressive souhaitée | streaming |
| gros volume indépendant | batch |
Le choix ne dépend donc pas uniquement de la taille.
20. Batch et Streaming répondent à des problèmes opposés
Le streaming cherche à :
show output earlier
Le batch accepte :
receive output later
pour optimiser un traitement massif.
Conceptuellement :
Streaming
→ optimize perceived latency
Batch
→ optimize offline throughput/cost
21. Exemple de génération de descriptions
Une marketplace possède :
30 000 products
Chaque fiche doit produire :
short marketing description
Il n’y a aucune interaction utilisateur immédiate.
Architecture appropriée :
30,000 products
↓
Batch
↓
30,000 descriptions
22. Exemple d’Evals
La Batch API peut également être intéressante pour exécuter de gros datasets d’évaluation.
Supposons :
5,000 evaluation cases
Chaque cas contient :
input
expected behavior
On peut générer les réponses en batch, puis calculer les métriques.
Conceptuellement :
Eval dataset
↓
Batch inference
↓
Model outputs
↓
Scoring
23. Batch et comparaison de modèles
On peut également exécuter :
Dataset
→ Model configuration A
puis :
Dataset
→ Model configuration B
et comparer :
quality
cost
latency
Cela rejoint le principe étudié dans les evals :
Les choix de modèle et de prompting doivent être mesurés sur des données représentatives.
24. Batch et Extended Thinking
Il faut toujours choisir le niveau de raisonnement approprié à la tâche.
Supposons :
50,000 simple classifications
Ajouter un raisonnement avancé à chaque requête peut augmenter fortement le coût.
Le raisonnement étudié précédemment reste valable :
simplest reasoning that passes evals
Le fait d’utiliser un batch ne justifie pas automatiquement davantage de reasoning.
25. Modèle + Reasoning + Batch sont des choix séparés
Il faut distinguer :
Which model?
Which reasoning mode?
Which execution mode?
Par exemple :
small model
+
simple prompting
+
batch
peut être idéal pour une classification massive.
Alors que :
more capable model
+
deeper reasoning
+
synchronous request
peut convenir à une analyse complexe interactive.
26. Batch et Structured Outputs
Pour un traitement massif, il est particulièrement utile d’obtenir des sorties faciles à traiter automatiquement.
Par exemple :
{
"category": "BILLING",
"confidence": "high"
}
Une structure stable simplifie :
batch results
↓
parsing
↓
database
27. Éviter le parsing fragile
Mauvaise sortie :
I believe this ticket probably belongs to the billing category.
Puis l’application tente de détecter :
contains("billing")
Pour des dizaines de milliers de résultats, ce type de parsing fragile devient rapidement problématique.
Une sortie contrainte est préférable.
28. Gestion des erreurs
Toutes les requêtes d’un batch ne réussissent pas nécessairement.
Il faut prévoir :
success
error
pour chaque élément.
Conceptuellement :
Batch
├── request A → success
├── request B → success
├── request C → error
└── request D → success
L’échec d’un élément ne doit pas nécessairement être interprété comme l’échec logique de tous les autres résultats.
29. Retry ciblé
Une bonne architecture peut identifier :
failed custom_id
puis relancer uniquement ces éléments.
Par exemple :
ticket-381 → success
ticket-382 → error
ticket-383 → success
Retry :
ticket-382
plutôt que retraiter automatiquement tout le batch.
30. Idempotency côté application
Pour les traitements qui écrivent ensuite dans une base, le custom_id peut également aider à éviter les doublons.
Conceptuellement :
custom_id
→ unique application record
Avant d’écrire :
Has result already been stored?
Cela devient particulièrement important lors des retries.
31. Ne pas confondre Retry API et Retry métier
Supposons que Claude retourne correctement :
TECHNICAL
mais que votre base de données soit temporairement indisponible.
Le problème n’est pas l’appel Claude.
Il est inutile de redemander la classification.
Il faut distinguer :
inference failed
de :
downstream persistence failed
Une architecture robuste traite séparément les deux problèmes.
32. Stocker les résultats avant transformation
Pour les gros workflows, une architecture peut conserver :
raw Claude result
avant les transformations métier.
Cela facilite :
- debugging ;
- replay ;
- audits ;
- analyse des erreurs.
Mais il faut évidemment appliquer les politiques appropriées de rétention et de sécurité des données.
33. Batch et Monitoring
Un traitement massif doit être observable.
Il est utile de suivre :
submitted requests
completed requests
failed requests
processing duration
token usage
cost
Puis éventuellement :
classification distribution
invalid output rate
retry rate
34. Exemple d’anomalie détectée
Supposons normalement :
BILLING = 30%
TECHNICAL = 60%
ESCALATION = 10%
Après modification du prompt :
ESCALATION = 78%
Même si le batch techniquement réussit, cela peut révéler une régression comportementale.
L’observabilité ne doit donc pas surveiller uniquement les erreurs HTTP.
35. Production = système mesurable
Cette idée revient dans tout le module.
Le pipeline doit permettre de répondre :
How many succeeded?
How many failed?
How much did it cost?
How long did it take?
Did quality change?
Pas seulement :
Did the API return something?
36. Batch et Rate Limits
Un avantage du traitement batch est que l’orchestration du gros volume est prise en charge comme un workload asynchrone plutôt que par une boucle applicative qui tente d’envoyer des milliers de requêtes interactives simultanément.
Mais le batch ne dispense pas de concevoir une application robuste.
Il faut toujours gérer :
submission errors
service limits
retry policy
result retrieval
37. Ne pas construire son propre pseudo-Batch inutilement
Anti-pattern :
for ticket in 50000_tickets:
call_claude(ticket)
sleep(...)
Cela impose à votre application :
- orchestration ;
- retry ;
- rate management ;
- longue durée d’exécution.
Lorsqu’un workload correspond réellement au modèle batch, utiliser l’API prévue pour cela peut simplifier l’architecture.
38. Mais ne pas utiliser Batch partout
Inversement :
Batch exists
→ use it for everything
serait une mauvaise conclusion.
Un utilisateur demandant :
Explain this error.
ne doit pas attendre le traitement différé d’un batch uniquement pour économiser du coût.
L’expérience utilisateur prime pour les interactions temps réel.
39. Exemple de décision
Question :
Do I need the answer now?
Si oui :
synchronous / streaming
Si non :
Can requests be processed independently?
Si oui :
batch candidate
40. Architecture hybride
Une même application peut utiliser plusieurs modes.
Par exemple, une plateforme support :
Interactive support assistant
→ streaming
et la nuit :
classify yesterday's 80,000 tickets
→ batch
et pour un incident complexe :
agentic investigation
→ tool loop
Il n’existe donc pas un mode d’appel unique pour toute l’application.
41. Choisir le mode selon le workload
On retrouve l’un des principes principaux du module :
Sync
Streaming
Async
Batch
sont des modes différents adaptés à des situations différentes.
La question est :
Is a user waiting?
Is the workload large?
Are requests independent?
How important is latency?
How important is cost?
42. Ce qu’il faut retenir pour la certification
Principe 1 — Batch pour les workloads Offline
No immediate user waiting
+
many requests
→ Batch candidate
Principe 2 — Les requêtes doivent être indépendantes
Le batch est particulièrement adapté lorsque chaque requête peut être traitée séparément.
Principe 3 — Utiliser custom_id
Chaque requête doit pouvoir être reliée sans ambiguïté à son résultat.
custom_id
→ request/result correlation
Principe 4 — Ne pas dépendre de l’ordre des résultats
Corrélez les résultats par identifiant.
Principe 5 — Batch échange Latence contre Coût/Throughput
higher latency acceptable
→ better fit for offline processing
Principe 6 — Batch ≠ Agent
Le batch exécute les tâches définies.
Il ne choisit pas dynamiquement le chemin.
Principe 7 — Batch ≠ Streaming
Streaming
→ user sees output earlier
Batch
→ user/application accepts output later
Principe 8 — Gérer les erreurs individuellement
Identifiez les éléments ayant échoué et relancez de manière ciblée lorsque cela est approprié.
Pièges fréquents à l’examen
Piège 1
« J’ai 50 000 utilisateurs simultanés, donc je dois utiliser Message Batches API. »
Pas nécessairement.
S’ils attendent tous une réponse interactive, le batch n’est pas adapté uniquement parce que le volume est important.
Piège 2
« Les résultats du batch peuvent être associés aux entrées uniquement par leur position. »
Mauvaise approche.
Utilisez custom_id.
Piège 3
« Un batch est une forme d’agent capable de gérer automatiquement un workflow complexe. »
Faux.
Il s’agit d’un mode de traitement asynchrone de plusieurs requêtes.
Piège 4
« Si une requête du batch échoue, il faut forcément relancer toutes les requêtes. »
Non.
Une architecture robuste identifie les requêtes concernées et peut appliquer un retry ciblé.
Piège 5
« Le batch est toujours préférable parce qu’il coûte moins cher. »
Non.
La latence supplémentaire le rend inadapté aux interactions temps réel.
Piège 6
« Batch et async/await signifient la même chose. »
Non.
async/await concerne la manière dont votre application gère l’exécution asynchrone.
La Message Batches API est un mode de traitement serveur conçu pour regrouper de nombreuses requêtes.
La règle à mémoriser
Pour choisir le batch :
Does a user need the answer immediately?
↓
Yes
↓
Sync / Streaming
No
↓
Are there many independent requests?
↓
Yes
↓
Batch
Puis :
Build requests
↓
Assign custom_id
↓
Submit batch
↓
Process asynchronously
↓
Retrieve results
↓
Match by custom_id
↓
Handle failures
↓
Store / evaluate
La Message Batches API illustre un principe général de production :
Le bon mode d’appel dépend du workload, pas uniquement des capacités du modèle.
Pour une application interactive, la priorité peut être la latence.
Pour un traitement massif nocturne, les priorités peuvent devenir :
cost
throughput
robustness
Le rôle de l’ingénieur est donc de choisir le mode d’exécution adapté plutôt que d’utiliser le même pattern pour tous les cas.
Récapitulatif de la série
Nous avons maintenant couvert :
Production-Grade Prompting
Extended Thinking
Tool Use
Streaming
Context Engineering
Agents & Human-in-the-Loop
Memory
Skills & CLAUDE.md
MCP
Multimodal
Message Batches API
Ces sujets forment ensemble une architecture mentale de production :
Prompt
↓
Model / reasoning
↓
Context
↓
Tools
↓
Application authorization
↓
State / Memory
↓
Validation
↓
Human approval
↓
Observability / Evals
Le principe central à retenir pour la certification est que Claude n’est qu’un composant du système.
La robustesse vient principalement de l’architecture construite autour de lui :
good prompts
+
good schemas
+
controlled tools
+
managed context
+
explicit state
+
evals
+
security
+
human approval when needed
