Llamadas a herramientas de grano fino

Cuando combinas el uso de herramientas con streaming en Claude, obtienes actualizaciones en tiempo real mientras la IA genera los argumentos de la herramienta. Esto crea una experiencia de usuario más receptiva, pero hay algunos detalles importantes que debes entender sobre cómo funciona esto detrás de escena.

Streaming básico de herramientas

Con el streaming habilitado, Claude envía diferentes tipos de eventos mientras procesa tu solicitud. Ya estás familiarizado con eventos como ContentBlockDelta para la generación de texto regular. Para el uso de herramientas, también necesitarás manejar un nuevo tipo de evento llamado InputJsonEvent.

Cada InputJsonEvent contiene dos propiedades clave:

partial_json - Un fragmento de JSON que representa parte de los argumentos de la herramienta
snapshot - El JSON acumulado construido a partir de todos los fragmentos recibidos hasta el momento

Así es como manejas estos eventos en tu pipeline de streaming:

python

for chunk in stream:
    if chunk.type == "input_json":
        # Procesar el fragmento JSON parcial
        print(chunk.partial_json)
        # O usar el snapshot completo hasta el momento
        current_args = chunk.snapshot

Cómo funciona la validación de JSON

Aquí es donde las cosas se vuelven interesantes. La API de Anthropic no te envía inmediatamente cada fragmento a medida que Claude lo genera. En su lugar, almacena en búfer los fragmentos y los valida primero.

La API espera a que los pares clave-valor de nivel superior estén completos antes de enviar nada. Por ejemplo, si tu herramienta espera esta estructura:

json

{
  "abstract": "This paper presents a novel...",
  "meta": {
    "word_count": 847,
    "review": "This paper introduces QuanNet..."
  }
}

La API hará lo siguiente:

Esperará hasta que el valor completo de abstract esté completo
Validará ese par clave-valor contra tu esquema
Enviará todos los fragmentos almacenados en búfer para abstract de una sola vez
Repetirá el proceso para el objeto meta

Este proceso de validación explica por qué ves retrasos seguidos de ráfagas de texto, incluso con el streaming habilitado. Los fragmentos se retienen hasta que un par clave-valor de nivel superior completo y válido esté listo.

Si necesitas un streaming más rápido y granular, quizás para mostrar a los usuarios actualizaciones inmediatas o comenzar a procesar resultados parciales rápidamente, puedes habilitar las llamadas a herramientas de grano fino.

Las llamadas a herramientas de grano fino hacen principalmente una cosa: deshabilitan la validación de JSON del lado de la API. Esto significa:

Obtienes los fragmentos en cuanto Claude los genera
No hay retrasos de almacenamiento en búfer entre las claves de nivel superior
Un comportamiento de streaming más tradicional
Crítico: la validación de JSON está deshabilitada; tu código debe manejar JSON inválido

Habilítalo agregando fine_grained=True a tu llamada a la API:

python

run_conversation(
    messages, 
    tools=[save_article_schema], 
    fine_grained=True
)

Con las llamadas a herramientas de grano fino, podrías recibir un valor de word_count mucho antes en el stream, sin esperar a que se complete todo el objeto meta.

Manejo de JSON inválido

Cuando usas llamadas a herramientas de grano fino, Claude podría generar JSON inválido como "word_count": undefined en lugar de un número adecuado. Tu aplicación necesita manejar estos casos con elegancia:

python

try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    # Maneja el JSON inválido de forma adecuada
    print("Received invalid JSON, continuing...")

Sin las llamadas a herramientas de grano fino, la validación de la API detectaría este error y potencialmente envolvería los valores problemáticos en cadenas de texto, lo cual podría no coincidir con tu esquema esperado.

Cuándo usar las llamadas a herramientas de grano fino

Considera habilitar las llamadas a herramientas de grano fino cuando:

Necesitas mostrar a los usuarios el progreso en tiempo real de la generación de argumentos de herramientas
Quieres comenzar a procesar resultados parciales de herramientas tan rápido como sea posible
Los retrasos de almacenamiento en búfer afectan negativamente tu experiencia de usuario
Te sientes cómodo implementando un manejo robusto de errores de JSON

Para la mayoría de las aplicaciones, el comportamiento predeterminado con validación es perfectamente adecuado. Pero cuando necesitas esa capacidad de respuesta adicional, las llamadas a herramientas de grano fino te dan el control para obtener los fragmentos tan rápido como Claude pueda generarlos.

Streaming básico de herramientas

Cómo funciona la validación de JSON