Le SDK Anthropic en direct : streaming, caching, structured output

Le choix : pas de framework entre l'app et le modèle

Le projet appelle Claude via AsyncAnthropic directement. Les quatre techniques ci-dessous expliquent pourquoi : chacune exige un contrôle fin que les abstractions génériques rendent laborieux.

1. Le streaming d'événements

async with client.messages.stream(model="claude-sonnet-4-6", messages=..., tools=...) as stream:
    async for event in stream:
        ...  # content_block_start / text_delta / input_json_delta / content_block_stop

Le SDK émet des événements typés : du texte (text_delta), mais aussi les arguments d'un tool call en cours de génération (input_json_delta). Le projet les traduit en événements internes provider-agnostiques, poussés en SSE (module 2) — l'UI voit l'agent « penser » en direct.

2. Le prompt caching : diviser la facture

Le system prompt du copilot (instructions + définitions de tools) fait des milliers de tokens identiques à chaque tour. Le cache d'Anthropic les fait payer une fois :

system = [{"type": "text", "text": LONG_SYSTEM, "cache_control": {"type": "ephemeral"}}]

Deuxième breakpoint posé sur le dernier message de l'historique : le préfixe de conversation (tours précédents) est lui aussi servi du cache à chaque nouveau tour. Sur un agent multi-tours, c'est le levier de coût/latence n°1 — et une raison majeure du SDK natif : le placement des breakpoints est chirurgical.

3. Le structured output via tool_use

Pour l'extraction, on ne « prie » pas pour du JSON valide : on force un tool dont le schéma EST le format de sortie :

tools=[{"name": "emit_order", "input_schema": EXTRACTION_OUTPUT_SCHEMA}],
tool_choice={"type": "tool", "name": "emit_order"}

Le modèle est contraint de produire un input conforme au JSON Schema — qu'on valide ensuite avec Pydantic (double rideau, module 1). C'est la technique la plus fiable pour obtenir du structuré.

4. Le budget de sortie et la troncature

max_tokens est configuré par tenant, et le cas stop_reason == "max_tokens" est géré explicitement : une réponse tronquée en plein tool call est jetée proprement (un tool_use partiel ré-injecté rend l'agent incohérent). Détail de prod devenu ADR — le genre de cas qu'un framework masque jusqu'à l'incident.