Transmisión de herramientas de grano fino

La transmisión de herramientas de grano fino está disponible en general en todos los modelos y todas las plataformas. Permite la transmisión de valores de parámetros de uso de herramientas sin almacenamiento en búfer ni validación JSON, reduciendo la latencia para comenzar a recibir parámetros grandes.

Cómo usar la transmisión de herramientas de grano fino

La transmisión de herramientas de grano fino está disponible en todos los modelos y todas las plataformas (Claude API, Amazon Bedrock, Google Vertex AI y Microsoft Foundry). Para usarla, establece eager_input_streaming en true en cualquier herramienta definida por el usuario donde desees que la transmisión de grano fino esté habilitada, y habilita la transmisión en tu solicitud.

Aquí hay un ejemplo de cómo usar la transmisión de herramientas de grano fino con la 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)

En este ejemplo, la transmisión de herramientas de grano fino permite que Claude transmita las líneas de un poema largo a 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.

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'

Acumulación de deltas de entrada de herramientas

Cuando un bloque de contenido tool_use se transmite, el evento inicial content_block_start contiene input: {} (un objeto vacío). Esto es un marcador de posición. La entrada real llega como una serie de eventos input_json_delta, cada uno llevando un fragmento de cadena partial_json. Tu código debe concatenar estos fragmentos y analizar el resultado una vez que el bloque se cierre.

El contrato de acumulación:

1. En content_block_start con type: "tool_use", inicializa una cadena vacía: input_json = ""
2. Para cada content_block_delta con type: "input_json_delta", añade: input_json += event.delta.partial_json
3. En content_block_stop, analiza la cadena acumulada: json.loads(input_json)

La discrepancia de tipo entre el input: {} inicial (objeto) y partial_json (cadena) es por diseño. El objeto vacío marca la ranura en la matriz de contenido; las cadenas delta construyen el valor real.

Manejo de JSON inválido en respuestas de herramientas

Al usar la transmisión de herramientas de grano fino, es posible que recibas 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 garantizar el manejo adecuado (con una clave razonable). Por ejemplo:

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

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.

Próximos pasos