Streaming de ferramentas de granularidade fina

O streaming de ferramentas de granularidade fina está geralmente disponível em todos os modelos e em todas as plataformas. Ele permite streaming de valores de parâmetros de uso de ferramentas sem buffering ou validação JSON, reduzindo a latência para começar a receber parâmetros grandes.

Como usar streaming de ferramentas de granularidade fina

O streaming de ferramentas de granularidade fina está disponível em todos os modelos e em todas as plataformas (Claude API, Amazon Bedrock, Google Vertex AI e Microsoft Foundry). Para usá-lo, defina eager_input_streaming como true em qualquer ferramenta definida pelo usuário onde você deseja que o streaming de granularidade fina seja ativado e ative o streaming em sua solicitação.

Aqui está um exemplo de como usar streaming de ferramentas de granularidade fina com a API:

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=65536,
    model="claude-opus-4-7",
    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?",
        }
    ],
) as stream:
    for event in stream:
        pass
    final_message = stream.get_final_message()

print(final_message.usage)

Neste exemplo, o streaming de ferramentas de granularidade fina permite que Claude transmita as linhas de um poema longo para a chamada de ferramenta make_file sem buffering para validar se o parâmetro lines_of_text é um JSON válido. Isso significa que você pode ver o parâmetro sendo transmitido conforme chega, sem ter que esperar que todo o parâmetro seja armazenado em buffer e validado.

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'

Acumulando deltas de entrada de ferramentas

Quando um bloco de conteúdo tool_use é transmitido, o evento inicial content_block_start contém input: {} (um objeto vazio). Este é um espaço reservado. A entrada real chega como uma série de eventos input_json_delta, cada um carregando um fragmento de string partial_json. Seu código deve concatenar esses fragmentos e analisar o resultado assim que o bloco fechar.

O contrato de acumulação:

1. Em content_block_start com type: "tool_use", inicialize uma string vazia: input_json = ""
2. Para cada content_block_delta com type: "input_json_delta", acrescente: input_json += event.delta.partial_json
3. Em content_block_stop, analise a string acumulada: json.loads(input_json)

A incompatibilidade de tipo entre o input: {} inicial (objeto) e partial_json (string) é intencional. O objeto vazio marca o slot no array de conteúdo; as strings delta constroem o valor real.

Tratando JSON inválido em respostas de ferramentas

Ao usar streaming de ferramentas de granularidade fina, 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 tratamento adequado (com uma chave razoável). Por exemplo:

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

Essa abordagem ajuda o modelo a entender que o conteúdo é JSON inválido enquanto preserva os dados malformados originais para fins de depuração.

Próximas etapas