Streaming de ferramentas refinado
O uso de ferramentas agora suporta streaming refinado para valores de parâmetros. Isso permite que desenvolvedores façam streaming de parâmetros de uso de ferramentas sem buffering / validação JSON, reduzindo a latência para começar a receber parâmetros grandes.
O streaming de ferramentas refinado é um recurso beta. Certifique-se de avaliar suas respostas antes de usá-lo em produção.
Use este formulário para fornecer feedback sobre a qualidade das respostas do modelo, a API em si, ou a qualidade da documentação—mal podemos esperar para ouvir de você!
Ao usar streaming de ferramentas refinado, você pode potencialmente receber entradas JSON inválidas ou parciais. Certifique-se de considerar esses casos extremos em seu código.
Como usar streaming de ferramentas refinado
Para usar este recurso beta, simplesmente adicione o cabeçalho beta fine-grained-tool-streaming-2025-05-14 a uma solicitação de uso de ferramenta e ative o streaming.
Aqui está um exemplo de como usar streaming de ferramentas refinado com a 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);Neste exemplo, o streaming de ferramentas refinado permite que Claude faça streaming das linhas de um poema longo para a chamada de ferramenta make_file sem buffering para validar se o parâmetro lines_of_text é JSON válido. Isso significa que você pode ver o parâmetro em streaming conforme ele chega, sem ter que esperar que todo o parâmetro seja armazenado em buffer e validado.
Com streaming de ferramentas refinado, os chunks de uso de ferramentas começam a fazer streaming mais rapidamente, e são frequentemente mais longos e contêm menos quebras de palavras. Isso se deve a diferenças no comportamento de chunking.
Exemplo:
Sem streaming refinado (atraso de 15s):
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'
...Com streaming refinado (atraso de 3s):
Chunk 1: '{"query": "TypeScript 5.0 5.1 5.2 5.3'
Chunk 2: ' new features comparison'Como o streaming refinado envia parâmetros sem buffering ou validação JSON, não há garantia de que o stream resultante será completado em uma string JSON válida.
Particularmente, se o motivo de parada max_tokens for atingido, o stream pode terminar no meio de um parâmetro e pode estar incompleto. Você geralmente terá que escrever suporte específico para lidar com quando max_tokens for atingido.
Lidando com JSON inválido em respostas de ferramentas
Ao usar streaming de ferramentas refinado, você pode receber JSON inválido ou incompleto do modelo. Se você precisar passar esse JSON inválido de volta para o modelo em um bloco de resposta de erro, você pode envolvê-lo em um objeto JSON para garantir o manuseio adequado (com uma chave razoável). Por exemplo:
{
"INVALID_JSON": "<sua string json inválida>"
}Esta abordagem ajuda o modelo a entender que o conteúdo é JSON inválido enquanto preserva os dados malformados originais para fins de depuração.
Ao envolver JSON inválido, certifique-se de escapar adequadamente quaisquer aspas ou caracteres especiais na string JSON inválida para manter a estrutura JSON válida no objeto wrapper.