Streaming d'outils à granularité fine
L'utilisation d'outils prend désormais en charge le streaming à granularité fine pour les valeurs de paramètres. Cela permet aux développeurs de diffuser les paramètres d'utilisation d'outils sans mise en mémoire tampon / validation JSON, réduisant la latence pour commencer à recevoir de gros paramètres.
Le streaming d'outils à granularité fine est une fonctionnalité bêta. Veuillez vous assurer d'évaluer vos réponses avant de l'utiliser en production.
Veuillez utiliser ce formulaire pour fournir des commentaires sur la qualité des réponses du modèle, l'API elle-même, ou la qualité de la documentation—nous avons hâte d'avoir de vos nouvelles !
Lors de l'utilisation du streaming d'outils à granularité fine, vous pourriez potentiellement recevoir des entrées JSON invalides ou partielles. Veuillez vous assurer de tenir compte de ces cas limites dans votre code.
Comment utiliser le streaming d'outils à granularité fine
Pour utiliser cette fonctionnalité bêta, ajoutez simplement l'en-tête bêta fine-grained-tool-streaming-2025-05-14 à une demande d'utilisation d'outils et activez le streaming.
Voici un exemple de comment utiliser le 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" \
-H "anthropic-beta: fine-grained-tool-streaming-2025-05-14" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 65536,
"tools": [
{
"name": "make_file",
"description": "Write text to a file",
"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
}' | jq '.usage'import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.stream(
max_tokens=65536,
model="claude-sonnet-4-5",
tools=[{
"name": "make_file",
"description": "Write text to a file",
"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?"
}],
betas=["fine-grained-tool-streaming-2025-05-14"]
)
print(response.usage)import Anthropic from '@anthropic-ai/sdk';
const anthropic = new Anthropic();
const message = await anthropic.beta.messages.stream({
model: "claude-sonnet-4-5",
max_tokens: 65536,
tools: [{
"name": "make_file",
"description": "Write text to a file",
"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?"
}],
betas: ["fine-grained-tool-streaming-2025-05-14"]
});
console.log(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 au fur et à mesure qu'il arrive, sans avoir à attendre que l'ensemble du paramètre soit mis en mémoire tampon et validé.
Avec le streaming d'outils à granularité fine, les fragments d'utilisation d'outils commencent à se diffuser plus rapidement, et sont souvent plus longs et contiennent moins de coupures de mots. Ceci est dû aux différences dans le comportement de fragmentation.
Exemple :
Sans streaming à granularité fine (délai de 15s) :
Fragment 1 : '{"'
Fragment 2 : 'query": "Ty'
Fragment 3 : 'peScri'
Fragment 4 : 'pt 5.0 5.1 '
Fragment 5 : '5.2 5'
Fragment 6 : '.3'
Fragment 8 : ' new f'
Fragment 9 : 'eatur'
...Avec streaming à granularité fine (délai de 3s) :
Fragment 1 : '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Fragment 2 : ' new features comparison'Parce que le streaming à granularité fine envoie des paramètres sans mise en mémoire tampon ou validation JSON, il n'y a aucune garantie que le flux résultant se terminera par une chaîne JSON valide.
Particulièrement, si la raison d'arrêt max_tokens est atteinte, le flux peut se terminer au milieu d'un paramètre et peut être incomplet. Vous devrez généralement écrire un support spécifique pour gérer quand max_tokens est atteint.
Gestion du JSON invalide dans les réponses d'outils
Lors de l'utilisation du streaming d'outils à granularité fine, vous pourriez 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 gestion appropriée (avec une clé raisonnable). Par exemple :
{
"INVALID_JSON": "<votre chaîne json invalide>"
}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.
Lors de l'enveloppement de JSON invalide, assurez-vous d'échapper correctement toutes les guillemets ou caractères spéciaux dans la chaîne JSON invalide pour maintenir une structure JSON valide dans l'objet enveloppant.