Appel d'outils à granularité fine

Lorsque vous combinez l'utilisation d'outils avec le streaming dans Claude, vous obtenez des mises à jour en temps réel à mesure que l'IA génère les arguments d'outils. Cela crée une expérience utilisateur plus réactive, mais il y a des détails importants à comprendre sur son fonctionnement en arrière-plan.

Streaming d'outils de base

Avec le streaming activé, Claude renvoie différents types d'événements à mesure qu'il traite votre requête. Vous connaissez déjà des événements comme ContentBlockDelta pour la génération de texte classique. Pour l'utilisation d'outils, vous devrez également gérer un nouveau type d'événement appelé InputJsonEvent.

Chaque InputJsonEvent contient deux propriétés clés :

partial_json - Un fragment de JSON représentant une partie des arguments de l'outil
snapshot - Le JSON cumulatif construit à partir de tous les fragments reçus jusqu'à présent

Voici comment gérer ces événements dans votre pipeline de streaming :

python

for chunk in stream:
    if chunk.type == "input_json":
        # Traiter le fragment JSON partiel
        print(chunk.partial_json)
        # Ou utiliser l'instantané complet jusqu'à présent
        current_args = chunk.snapshot

Comment fonctionne la validation JSON

C'est là que les choses deviennent intéressantes. L'API Anthropic ne vous envoie pas immédiatement chaque fragment à mesure que Claude le génère. Au lieu de cela, elle met en mémoire tampon les fragments et les valide d'abord.

L'API attend que les paires clé-valeur de premier niveau soient complètes avant d'envoyer quoi que ce soit. Par exemple, si votre outil attend cette structure :

json

{
  "abstract": "This paper presents a novel...",
  "meta": {
    "word_count": 847,
    "review": "This paper introduces QuanNet..."
  }
}

L'API va :

Attendre que la valeur entière de abstract soit complète
Valider cette paire clé-valeur par rapport à votre schéma
Envoyer tous les fragments mis en mémoire tampon pour abstract en une seule fois
Répéter le processus pour l'objet meta

Ce processus de validation explique pourquoi vous observez des délais suivis de rafales de texte, même avec le streaming activé. Les fragments sont retenus jusqu'à ce qu'une paire clé-valeur de premier niveau complète et valide soit prête.

Si vous avez besoin d'un streaming plus rapide et plus granulaire - peut-être pour montrer aux utilisateurs des mises à jour immédiates ou commencer à traiter rapidement des résultats partiels - vous pouvez activer l'appel d'outils à granularité fine.

L'appel d'outils à granularité fine fait une chose principale : il désactive la validation JSON côté API. Cela signifie :

Vous obtenez les fragments dès que Claude les génère
Aucun délai de mise en mémoire tampon entre les clés de premier niveau
Un comportement de streaming plus traditionnel
Critique : La validation JSON est désactivée - votre code doit gérer le JSON invalide

Activez-le en ajoutant fine_grained=True à votre appel API :

python

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

Avec l'appel d'outils à granularité fine, vous pourriez recevoir une valeur word_count beaucoup plus tôt dans le flux, sans attendre que l'objet meta entier soit complété.

Gestion du JSON invalide

Lorsque vous utilisez l'appel d'outils à granularité fine, Claude peut générer du JSON invalide comme "word_count": undefined au lieu d'un nombre approprié. Votre application doit gérer ces cas avec élégance :

python

try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    # Gérer correctement le JSON invalide
    print("Received invalid JSON, continuing...")

Sans l'appel d'outils à granularité fine, la validation de l'API détecterait cette erreur et pourrait envelopper les valeurs problématiques dans des chaînes, ce qui pourrait ne pas correspondre à votre schéma attendu.

Quand utiliser l'appel d'outils à granularité fine

Envisagez d'activer l'appel d'outils à granularité fine lorsque :

Vous devez montrer aux utilisateurs la progression en temps réel de la génération des arguments d'outils
Vous souhaitez commencer à traiter les résultats partiels des outils le plus rapidement possible
Les délais de mise en mémoire tampon nuisent à votre expérience utilisateur
Vous êtes à l'aise pour implémenter une gestion robuste des erreurs JSON

Pour la plupart des applications, le comportement par défaut avec validation est parfaitement adéquat. Mais lorsque vous avez besoin de cette réactivité supplémentaire, l'appel d'outils à granularité fine vous donne le contrôle pour obtenir les fragments aussi rapidement que Claude peut les générer.

Streaming d'outils de base

Comment fonctionne la validation JSON