Streaming de herramientas de grano fino
El uso de herramientas ahora admite streaming de grano fino para valores de parámetros. Esto permite a los desarrolladores transmitir parámetros de uso de herramientas sin almacenamiento en búfer / validación JSON, reduciendo la latencia para comenzar a recibir parámetros grandes.
El streaming de herramientas de grano fino es una característica beta. Por favor, asegúrate de evaluar tus respuestas antes de usarla en producción.
Por favor, usa este formulario para proporcionar comentarios sobre la calidad de las respuestas del modelo, la API en sí, o la calidad de la documentación—¡no podemos esperar a escuchar de ti!
Al usar el streaming de herramientas de grano fino, potencialmente puedes recibir entradas JSON inválidas o parciales. Por favor, asegúrate de tener en cuenta estos casos extremos en tu código.
Cómo usar el streaming de herramientas de grano fino
Para usar esta característica beta, simplemente agrega el encabezado beta fine-grained-tool-streaming-2025-05-14 a una solicitud de uso de herramientas y activa el streaming.
Aquí tienes un ejemplo de cómo usar el streaming de herramientas de grano fino con la 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);En este ejemplo, el streaming de herramientas de grano fino permite a Claude transmitir las líneas de un poema largo en la llamada de herramienta make_file sin almacenar en búfer para validar si el parámetro lines_of_text es JSON válido. Esto significa que puedes ver el parámetro transmitirse a medida que llega, sin tener que esperar a que todo el parámetro se almacene en búfer y se valide.
Con el streaming de herramientas de grano fino, los fragmentos de uso de herramientas comienzan a transmitirse más rápido, y a menudo son más largos y contienen menos saltos de palabra. Esto se debe a diferencias en el comportamiento de fragmentación.
Ejemplo:
Sin streaming de grano fino (retraso de 15s):
Fragmento 1: '{"'
Fragmento 2: 'query": "Ty'
Fragmento 3: 'peScri'
Fragmento 4: 'pt 5.0 5.1 '
Fragmento 5: '5.2 5'
Fragmento 6: '.3'
Fragmento 8: ' new f'
Fragmento 9: 'eatur'
...Con streaming de grano fino (retraso de 3s):
Fragmento 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Fragmento 2: ' new features comparison'Debido a que el streaming de grano fino envía parámetros sin almacenamiento en búfer o validación JSON, no hay garantía de que el flujo resultante se complete en una cadena JSON válida.
Particularmente, si se alcanza la razón de parada max_tokens, el flujo puede terminar a la mitad de un parámetro y puede estar incompleto. Generalmente tendrás que escribir soporte específico para manejar cuando se alcanza max_tokens.
Manejo de JSON inválido en respuestas de herramientas
Al usar el streaming de herramientas de grano fino, puedes recibir JSON inválido o incompleto del modelo. Si necesitas pasar este JSON inválido de vuelta al modelo en un bloque de respuesta de error, puedes envolverlo en un objeto JSON para asegurar el manejo adecuado (con una clave razonable). Por ejemplo:
{
"INVALID_JSON": "<tu cadena json inválida>"
}Este enfoque ayuda al modelo a entender que el contenido es JSON inválido mientras preserva los datos malformados originales para propósitos de depuración.
Al envolver JSON inválido, asegúrate de escapar adecuadamente cualquier comilla o carácter especial en la cadena JSON inválida para mantener la estructura JSON válida en el objeto envolvente.