Referencia de tipos del SDK de TypeScript para bloques de contenido

El SDK @anthropic-ai/sdk tipifica el contenido de la respuesta de Claude como una unión discriminada de tipos de bloques de contenido, indexada por un campo type. Esta página es una referencia rápida para los tipos de bloque que verás con más frecuencia en response.content, y el patrón de reducción de tipo que TypeScript requiere antes de que puedas acceder a un campo específico del bloque.

Cómo usar esta referencia

• Busca el tipo de bloque por su cadena .type, luego copia el fragmento de reducción de tipo que coincida con tu forma de iterar (cadena if vs switch).
• Trata .type como el único campo en el que puedes confiar antes de la reducción. Cada otro campo es específico de un miembro de la unión.
• Usa la tabla comparativa como una referencia cuando leas el bucle de otra persona sobre response.content y necesites saber qué expone un bloque determinado.
• Recuerda que hay dos uniones relacionadas: ContentBlock (lo que Claude te envía) y los tipos de parámetro de bloque como ToolResultBlockParam (lo que envías a Claude al construir mensajes). No son intercambiables.

Tipos de bloques de contenido de un vistazo

La unión que tipifica response.content incluye otros miembros además de estos tres para casos menos comunes (actividad de herramientas del lado del servidor, pensamiento redactado y similares). Los tres anteriores son aquellos a los que un bucle de manejo de respuesta típico reduce.

TextBlock

TextBlock es el texto de respuesta ordinario de Claude. Es el tipo de bloque al que reducirás con más frecuencia.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Di hola en una frase." }],
});
 
for (const block of response.content) {
  if (block.type === "text") {
    // TypeScript ahora sabe que `block` es un TextBlock aquí.
    console.log(block.text);
  }
}

ToolUseBlock

ToolUseBlock aparece cuando Claude decide llamar a una de las herramientas que proporcionaste. .input está tipificado como unknown porque su forma depende del input_schema de la herramienta, por lo que aún necesitas validarlo o convertirlo antes de usarlo.

for (const block of response.content) {
  if (block.type === "tool_use") {
    // block.id, block.name, block.input están todos disponibles aquí.
    console.log(block.id, block.name, block.input);
  }
}

ThinkingBlock

ThinkingBlock contiene la salida de pensamiento extendido de Claude. Solo aparece en response.content cuando el pensamiento extendido está habilitado para la solicitud; de lo contrario, simplemente está ausente, no presente con un valor vacío.

for (const block of response.content) {
  if (block.type === "thinking") {
    console.log(block.thinking);
  }
}

Reducción con una declaración switch

Una cadena if funciona, pero un switch en block.type se lee mejor una vez que estás manejando tres o más tipos de bloque en el mismo bucle, y mantiene el tipo reducido de cada rama aislado:

for (const block of response.content) {
  switch (block.type) {
    case "text":
      console.log(block.text);
      break;
    case "tool_use":
      console.log(block.name, block.input);
      break;
    case "thinking":
      console.log(block.thinking);
      break;
    default:
      // Otros tipos de bloque en la unión aterrizan aquí, sin reducir.
      break;
  }
}

Filtrar a un solo tipo de bloque

Cuando solo te interesa un tipo de bloque, filtra primero en lugar de ramificar dentro del bucle. TypeScript reduce el tipo de elemento del array a través de un predicado de tipo:

const toolCalls = response.content.filter(
  (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
);
 
for (const call of toolCalls) {
  console.log(call.name, call.input); // no se necesita más reducción
}

Los tipos de parámetros de bloque son una unión separada

TextBlock, ToolUseBlock y ThinkingBlock describen lo que Claude te envía. Cuando construyes mensajes para enviar a Claude, usas los tipos de parámetro correspondientes en su lugar, como ToolResultBlockParam para devolver el resultado de una herramienta. Estos tipos de parámetro no son los mismos tipos de TypeScript que los bloques de respuesta, incluso donde los nombres se superponen, así que no reutilices un ToolUseBlock que recibiste como si fuera contenido de entrada válido.

const toolResultMessage: Anthropic.MessageParam = {
  role: "user",
  content: [
    {
      type: "tool_result",
      tool_use_id: call.id,
      content: "72°F y soleado",
    },
  ],
};

Preguntas frecuentes

Relacionado

• El modelo mental del SDK de TypeScript de Anthropic - cómo el cliente, las solicitudes y las respuestas encajan antes de llegar a los tipos de bloque individuales
• Conceptos básicos del SDK de TypeScript/JavaScript - instalar el SDK y hacer tu primera solicitud
• Definiciones de herramientas fuertemente tipadas con Zod en TypeScript - validar el .input de un ToolUseBlock contra un esquema real
• Referencia de clases de error del SDK de TypeScript - la página de referencia correspondiente para clases de error tipadas en lugar de bloques de contenido
• Manejo de solicitudes de uso de herramientas y devolución de bloques de resultados de herramientas - el ciclo completo desde ToolUseBlock hasta una respuesta ToolResultBlockParam

Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de TypeScript @anthropic-ai/sdk (última versión). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.