Streaming d'outils à granularité fine

Le streaming d'outils à granularité fine est généralement disponible sur tous les modèles et toutes les plateformes. Il permet le streaming des valeurs de paramètres d'utilisation d'outils sans mise en mémoire tampon ni validation JSON, réduisant la latence pour commencer à recevoir de grands paramètres.

Comment utiliser le streaming d'outils à granularité fine

Le streaming d'outils à granularité fine est disponible sur tous les modèles et toutes les plateformes (Claude API, Amazon Bedrock, Google Vertex AI et Microsoft Foundry). Pour l'utiliser, définissez eager_input_streaming sur true sur tout outil défini par l'utilisateur pour lequel vous souhaitez activer le streaming à granularité fine, et activez le streaming sur votre requête.

Voici un exemple de la façon d'utiliser le streaming d'outils à granularité fine avec l'API :

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=65536,
    model="claude-opus-4-7",
    tools=[
        {
            "name": "make_file",
            "description": "Write text to a file",
            "eager_input_streaming": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "filename": {
                        "type": "string",
                        "description": "The filename to write text to",
                    },
                    "lines_of_text": {
                        "type": "array",
                        "description": "An array of lines of text to write to the file",
                    },
                },
                "required": ["filename", "lines_of_text"],
            },
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Can you write a long poem and make a file called poem.txt?",
        }
    ],
) as stream:
    for event in stream:
        pass
    final_message = stream.get_final_message()

print(final_message.usage)

Dans cet exemple, le streaming d'outils à granularité fine permet à Claude de diffuser les lignes d'un long poème dans l'appel d'outil make_file sans mise en mémoire tampon pour valider si le paramètre lines_of_text est un JSON valide. Cela signifie que vous pouvez voir le paramètre se diffuser à mesure qu'il arrive, sans avoir à attendre que le paramètre entier soit mis en mémoire tampon et validé.

Chunk 1: '{"'
Chunk 2: 'query": "Ty'
Chunk 3: 'peScri'
Chunk 4: 'pt 5.0 5.1 '
Chunk 5: '5.2 5'
Chunk 6: '.3'
Chunk 8: ' new f'
Chunk 9: 'eatur'
...

Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'

Accumulation des deltas d'entrée d'outil

Lorsqu'un bloc de contenu tool_use se diffuse, l'événement initial content_block_start contient input: {} (un objet vide). C'est un espace réservé. L'entrée réelle arrive sous la forme d'une série d'événements input_json_delta, chacun portant un fragment de chaîne partial_json. Votre code doit concaténer ces fragments et analyser le résultat une fois que le bloc se ferme.

Le contrat d'accumulation :

1. Sur content_block_start avec type: "tool_use", initialisez une chaîne vide : input_json = ""
2. Pour chaque content_block_delta avec type: "input_json_delta", ajoutez : input_json += event.delta.partial_json
3. Sur content_block_stop, analysez la chaîne accumulée : json.loads(input_json)

L'inadéquation de type entre l'input: {} initial (objet) et partial_json (chaîne) est intentionnelle. L'objet vide marque l'emplacement dans le tableau de contenu ; les chaînes delta construisent la valeur réelle.

import json
import anthropic

client = anthropic.Anthropic()

tool_inputs = {}  # index -> accumulated JSON string

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "eager_input_streaming": True,
            "input_schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
    messages=[{"role": "user", "content": "Weather in Paris?"}],
) as stream:
    for event in stream:
        if (
            event.type == "content_block_start"
            and event.content_block.type == "tool_use"
        ):
            tool_inputs[event.index] = ""
        elif (
            event.type == "content_block_delta"
            and event.delta.type == "input_json_delta"
        ):
            tool_inputs[event.index] += event.delta.partial_json
        elif event.type == "content_block_stop" and event.index in tool_inputs:
            parsed = json.loads(tool_inputs[event.index])
            print(f"Tool input: {parsed}")

Gestion du JSON invalide dans les réponses d'outils

Lors de l'utilisation du streaming d'outils à granularité fine, vous pouvez recevoir du JSON invalide ou incomplet du modèle. Si vous devez renvoyer ce JSON invalide au modèle dans un bloc de réponse d'erreur, vous pouvez l'envelopper dans un objet JSON pour assurer une manipulation appropriée (avec une clé raisonnable). Par exemple :

{
  "INVALID_JSON": "<your invalid json string>"
}

Cette approche aide le modèle à comprendre que le contenu est un JSON invalide tout en préservant les données malformées d'origine à des fins de débogage.

Étapes suivantes