Hacer streaming de llamadas a herramientas de la API de Claude dentro de un bucle

Hacer streaming de una respuesta de chat es fácil. Hacer streaming de una respuesta que además llama a tus herramientas es donde la mayoría se equivoca en la forma del mensaje, pierde el bloque tool_use del asistente o termina con un bucle que nunca corta. El problema de fondo no es el streaming: es que usar herramientas convierte una sola petición en un bucle agéntico con reglas estrictas sobre la forma del turno, y la capa de streaming facilita saltárselas sin darte cuenta. Al terminar esta guía vas a tener un bucle funcional en TypeScript que emite tokens al usuario, pausa de forma limpia para ejecutar una herramienta, le devuelve el resultado con la forma exacta que la API espera y se detiene justo cuando debe.

01 · Requisitos previos y el modelo mental

Antes de escribir código, deja claras dos cosas.

El modelo mental pesa más que la sintaxis. Una petición normal es un solo viaje de ida y vuelta: mandas messages, Claude te devuelve texto por streaming y listo. Una petición con herramientas es un bucle:

1. Haces streaming de una respuesta. Claude o bien responde en texto, o bien decide que necesita una herramienta y se detiene con un stop_reason igual a «tool_use».
2. Ante «tool_use», pausas, lees el nombre y el input de la herramienta en la respuesta, y la ejecutas en tu propio código.
3. Agregas dos cosas a la conversación: la respuesta completa del asistente (la que contiene el bloque tool_use) y un mensaje de usuario que lleva el tool_result; luego vuelves a llamar a la API.
4. Repites hasta que Claude se detiene con «end_turn».

La API no guarda estado: no recuerda nada entre llamadas, así que el historial de mensajes y el bucle corren por tu cuenta. Las herramientas son una función del único endpoint /v1/messages, no una API aparte: tú las describes, Claude las pide, tú las ejecutas. Esa repartición (Claude decide, tu harness ejecuta) es la clave de todo.

02 · Define la herramienta y el ejecutor

Una definición de herramienta consta de un nombre, una description que Claude lee para decidir cuándo llamarla y un JSON Schema para su input. Sé bien específico en la description: di en qué momento llamarla, no solo qué hace. Los modelos Opus recientes recurren a las herramientas con más cautela, así que una condición de disparo clara sube de forma medible la probabilidad de que decida usarla cuando toca.

import Anthropic from "@anthropic-ai/sdk"

const client = new Anthropic()

const tools: Anthropic.Tool[] = [
  {
    name: "get_weather",
    description:
      "Obtiene el clima actual de una ciudad. Llama a esta herramienta cuando " +
      "el usuario pregunte por las condiciones actuales, la temperatura, o si " +
      "debe llevar abrigo.",
    input_schema: {
      type: "object",
      properties: {
        city: { type: "string", description: "Nombre de ciudad, ej. Santo Domingo" },
        unit: { type: "string", enum: ["celsius", "fahrenheit"] },
      },
      required: ["city"],
    },
  },
]

// Tu lógica real de la herramienta. Devuelve un string (o JSON.stringify de un objeto).
async function runTool(name: string, input: unknown): Promise<string> {
  if (name === "get_weather") {
    const { city } = input as { city: string }
    // ...aquí llamas a una API de clima real...
    return JSON.stringify({ city, tempC: 29, sky: "húmedo, nubes dispersas" })
  }
  return JSON.stringify({ error: `herramienta desconocida: ${name}` })
}

Dos detalles que ahorran horas de debug. Primero, mantén el esquema plano y con nombres de propiedad descriptivos: los campos muy anidados o ambiguos disparan la tasa de error. Segundo, trata el input que manda Claude como datos sin tipar que tienes que validar, no como verdad absoluta. Un esquema restringe la forma, no la corrección de negocio.

Por qué un resultado en string es suficiente

El contenido del tool_result puede ser un string plano o bloques estructurados. Un string es lo más simple que funciona; usa contenido estructurado solo cuando devuelves imágenes o necesitas citas. Si tu herramienta falla, devuelve el error como resultado con is_error en true, para que Claude se adapte en vez de andar adivinando.

03 · Haz streaming del primer turno

Usa el helper de streaming del SDK. Él va juntando los deltas que llegan en bloques de contenido completos, así que no tienes que reducir a mano los eventos content_block_delta hasta armar el mensaje.

let messages: Anthropic.MessageParam[] = [
  { role: "user", content: "¿Qué me pongo hoy en Santo Domingo?" },
]

const stream = client.messages.stream({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  tools,
  messages,
})

// Muestra el texto visible al usuario conforme va llegando.
stream.on("text", (delta) => process.stdout.write(delta))

const final = await stream.finalMessage()

El evento text te entrega solo el delta como string: más simple que filtrar a mano los eventos de delta crudos. Usa finalMessage() para obtener el Anthropic.Message completo y ya armado cuando el stream termina; maneja por dentro los estados de cierre, error y aborto, así que no envuelvas los handlers .on() en un Promise hecho a mano solo para juntar el resultado.

04 · Detecta la llamada, ejecútala y devuelve el resultado

Este es el meollo del asunto, y es donde las reglas de forma del mensaje no perdonan.

if (final.stop_reason === "tool_use") {
  // 1. Mete el contenido COMPLETO del asistente, incluido el bloque tool_use.
  messages.push({ role: "assistant", content: final.content })

  // 2. Un mismo turno puede traer VARIOS bloques tool_use. Ejecútalos todos.
  const toolUses = final.content.filter(
    (b): b is Anthropic.ToolUseBlock => b.type === "tool_use",
  )

  const toolResults: Anthropic.ToolResultBlockParam[] = []
  for (const call of toolUses) {
    const result = await runTool(call.name, call.input) // el input ya viene parseado
    toolResults.push({
      type: "tool_result",
      tool_use_id: call.id, // debe coincidir con el bloque tool_use de origen
      content: result,
    })
  }

  // 3. TODOS los resultados vuelven en UN solo mensaje de usuario, y luego el bucle.
  messages.push({ role: "user", content: toolResults })
}

Tres reglas que la API impone, y cada una falla de forma escandalosa si la rompes:

1. Mete el contenido completo del asistente antes del tool_result. Si agregas un tool_result armado a mano sin el turno previo del asistente que contiene el bloque tool_use, la API rechaza la petición: un tool_result sin su tool_use correspondiente está malformado.
2. Haz coincidir cada tool_use_id. Cada tool_result debe traer el tool_use_id del bloque al que responde. Si no coincide o lo omites, el turno se rechaza.
3. Responde todas las llamadas en un mismo mensaje de usuario. Cuando un turno trae varios bloques tool_use, junta todos los tool_results en un solo mensaje de usuario: ni uno por llamada, ni uno por vuelta del bucle. El SDK ya expone call.input como objeto parseado; no compares strings crudos sobre el JSON serializado, porque el escapado puede variar entre versiones del modelo.

05 · Cierra el bucle y detente a tiempo

El fragmento de arriba maneja una sola ronda de herramienta. Un agente de verdad lo envuelve en un bucle acotado que vuelve a hacer streaming tras cada ronda hasta que Claude termina.

async function runConversation(userText: string, maxTurns = 8) {
  let messages: Anthropic.MessageParam[] = [
    { role: "user", content: userText },
  ]

  for (let turn = 0; turn < maxTurns; turn++) {
    const stream = client.messages.stream({
      model: "claude-opus-4-8",
      max_tokens: 1024,
      tools,
      messages,
    })
    stream.on("text", (d) => process.stdout.write(d))
    const final = await stream.finalMessage()

    if (final.stop_reason === "end_turn") return final
    if (final.stop_reason === "pause_turn") {
      // Trabajo del lado del servidor pausado a mitad de turno. Reenvía para reanudar; no agregues ningún mensaje.
      messages.push({ role: "assistant", content: final.content })
      continue
    }
    if (final.stop_reason !== "tool_use") return final

    messages.push({ role: "assistant", content: final.content })
    const results: Anthropic.ToolResultBlockParam[] = []
    for (const b of final.content) {
      if (b.type === "tool_use") {
        results.push({
          type: "tool_result",
          tool_use_id: b.id,
          content: await runTool(b.name, b.input),
        })
      }
    }
    messages.push({ role: "user", content: results })
  }
  throw new Error("el bucle de herramientas superó el máximo de turnos permitido")
}

Fíjate en la rama pause_turn. Cuando usas herramientas del lado del servidor (búsqueda web, ejecución de código) la API corre su propio bucle de sampling; si alcanza su límite interno a mitad de turno, devuelve pause_turn. La solución es agregar el contenido del asistente y reenviar: el servidor reanuda por su cuenta. No le inyectes un mensaje de "continúa"; el bloque de herramienta del servidor que queda al final le dice a la API que retome donde se quedó.

06 · Ejemplo resuelto y errores comunes

Sigamos el ejemplo del clima de principio a fin. Turno 0: mandas "¿qué me pongo hoy en Santo Domingo?". Claude transmite un breve preámbulo y luego se detiene con stop_reason «tool_use», pidiendo get_weather con input { city: "Santo Domingo" }. Agregas el turno del asistente, ejecutas la herramienta, recibes el JSON y lo metes como tool_result. Turno 1: vuelves a hacer streaming; ahora Claude ya tiene el clima y transmite la respuesta final ("Está húmedo y rondando los 29 °C: ropa ligera y transpirable, y una sombrilla por las nubes dispersas"), deteniéndose con «end_turn». El bucle termina. Dos llamadas a la API, una ejecución de herramienta, y todo con streaming en ambas.

Los errores que de verdad te complican:

• Olvidar el turno del asistente. El bug más común, por mucho: agregar el tool_result sin agregar primero el mensaje del asistente que contiene el bloque tool_use. El resultado es un 400 por un tool_result huérfano. Mete el contenido del asistente primero, siempre.
• Manejar solo el primer bloque tool_use. Claude puede disparar varias llamadas a herramientas en un mismo turno (el clima de dos ciudades, por ejemplo). Si manejas solo la primera, la API rechaza el siguiente turno por un tool_result faltante. Recórrelas todas.
• El buffering del proxy mata el stream. Si haces streaming a través de un reverse proxy (Traefik, nginx) o un host que almacena las respuestas en buffer, el usuario no ve nada hasta el final: el streaming queda anulado en silencio. Confirma que la ruta no esté bufferizada y nunca acumules el stream en un solo string antes de reenviarlo.
• Quedarte corto con max_tokens. Si el modelo alcanza max_tokens a mitad de una llamada a herramienta, el input de la herramienta queda truncado y la llamada es inservible. Dale aire; 1024 está bien para herramientas pequeñas, y más para respuestas largas.
• Forzar la herramienta equivocada. Deja tool_choice en su default («auto») para que Claude también pueda simplemente responder. Usa tool_choice con { type: "tool", name } solo cuando de verdad necesites forzar una herramienta específica (por ejemplo, para garantizar una extracción estructurada) y acompáñalo con disable_parallel_tool_use si quieres como mucho una llamada por turno.

Ese es todo el patrón: un bucle acotado alrededor del helper de streaming, el turno del asistente metido antes de cada tool_result, cada tool_use_id haciendo coincidencia, y todas las llamadas respondidas en un mismo mensaje. Acierta esos cuatro y el streaming con herramientas deja de ser frágil para convertirse en la columna confiable de un agente. Todo lo más elaborado (herramientas en paralelo, herramientas del lado del servidor, una UI de chat que lee el stream por SSE) es el mismo bucle con más eventos que escuchar.