Streaming granulaire des appels d'outils

Quand on combine le streaming avec l’utilisation d’outils, Claude envoie les arguments des outils au fur et a mesure qu’il les genere. Cela permet de rendre l’interface plus reactive. Mais il y a des subtilites a comprendre sur le fonctionnement interne.

Le streaming standard avec les outils

En mode streaming, Claude envoie differents types d’evenements. Pour les outils, un nouveau type apparait : InputJsonEvent.

Chaque InputJsonEvent contient deux proprietes :

• partial_json : un fragment du JSON des arguments de l’outil
• snapshot : le JSON complet accumule jusqu’a present

for chunk in stream:
    if chunk.type == "input_json":
        # Traiter le fragment JSON
        print(chunk.partial_json)
        # Ou utiliser le snapshot complet
        current_args = chunk.snapshot

La validation JSON cote API

Par defaut, l’API Anthropic ne transmet pas chaque fragment immediatement. Elle met en tampon les morceaux et les valide avant de les envoyer.

Concretement, l’API attend qu’une paire cle-valeur de premier niveau soit complete avant de l’envoyer. Prenons cette structure :

{
  "abstract": "Cet article presente une nouvelle...",
  "meta": {
    "word_count": 847,
    "review": "Cet article introduit QuanNet..."
  }
}

L’API va :

1. Attendre que toute la valeur de abstract soit generee
2. Valider cette paire cle-valeur contre le schema
3. Envoyer d’un coup tous les fragments bufferises pour abstract
4. Repeter le processus pour meta

C’est pourquoi on observe des pauses suivies de rafales de texte, meme en mode streaming. Les fragments sont retenus jusqu’a ce qu’une paire cle-valeur complete et valide soit prete.

Le mode granulaire (fine-grained)

Si vous avez besoin d’un streaming plus rapide et plus fin — par exemple pour afficher une progression en temps reel — vous pouvez activer le mode granulaire.

Ce mode fait une chose principale : il desactive la validation JSON cote API. Consequences :

• Les fragments arrivent des que Claude les genere
• Plus de delai de mise en tampon entre les cles de premier niveau
• Comportement de streaming plus traditionnel
• Attention : la validation JSON est desactivee, votre code doit gerer les JSON invalides

Pour l’activer :

run_conversation(
    messages,
    tools=[save_article_schema],
    fine_grained=True
)

Avec ce mode, une valeur comme word_count peut arriver bien plus tot dans le flux, sans attendre que tout l’objet meta soit complete.

Gerer les JSON invalides

En mode granulaire, Claude peut generer du JSON invalide (par exemple "word_count": undefined au lieu d’un nombre). Votre application doit gerer ces cas :

try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    # Gerer le JSON invalide
    print("JSON invalide recu, on continue...")

Sans le mode granulaire, la validation de l’API detecterait cette erreur et pourrait encapsuler les valeurs problematiques dans des chaines de caracteres — ce qui ne correspondrait peut-etre pas a votre schema.

Quand utiliser le mode granulaire ?

Activez-le quand :

• Vous devez montrer la progression en temps reel de la generation des arguments
• Vous voulez commencer a traiter des resultats partiels le plus tot possible
• Les delais de mise en tampon degradent l’experience utilisateur
• Vous etes pret a implementer une gestion robuste des erreurs JSON

Pour la plupart des applications, le comportement par defaut avec validation est parfaitement adapte. Le mode granulaire est reserve aux cas ou la reactivite est critique.