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 ainsi 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 (API Claude, 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 d'utilisation du streaming d'outils à granularité fine avec l'API :

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 65536,
    "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?"
      }
    ],
    "stream": true
  }'

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 au fur et à mesure de son arrivée, sans avoir à attendre que l'intégralité du paramètre soit mise en mémoire tampon et validée.

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 est diffusé, l'événement initial content_block_start contient input: {} (un objet vide). Il s'agit d'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 le bloc fermé.

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)

La discordance de type entre le 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-6",
    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 transmettre ce JSON invalide au modèle dans un bloc de réponse d'erreur, vous pouvez l'encapsuler dans un objet JSON pour garantir une gestion correcte (avec une clé raisonnable). Par exemple :

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

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

Prochaines étapes