O uso de ferramentas agora suporta streaming granular para valores de parâmetros. Isso permite que os 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 granular é 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 própria API ou a qualidade da documentação—mal podemos esperar para ouvir de você!

Ao usar streaming de ferramentas granular, 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 granular

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 granular 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-20250514",
    "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'

Neste exemplo, o streaming de ferramentas granular 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 fazer streaming conforme chega, sem ter que esperar que todo o parâmetro seja armazenado em buffer e validado.

Com streaming de ferramentas granular, 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 granular (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 granular (atraso de 3s):

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

Como o streaming granular 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 granular, você pode receber JSON inválido ou incompleto do modelo. Se você precisar passar este 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.