Referência de Tipos do SDK TypeScript para Blocos de Conteúdo

O SDK @anthropic-ai/sdk tipa o conteúdo de uma resposta do Claude como uma união discriminada de tipos de bloco de conteúdo, indexada por um campo type. Esta página é uma referência rápida para os tipos de bloco que você verá com mais frequência em response.content e o padrão de "narrowing" (estreitamento de tipo) que o TypeScript exige antes que você possa acessar um campo específico do bloco.

Como Usar Esta Referência

• Procure o tipo de bloco pelo seu string .type, depois copie o snippet de "narrowing" que corresponde à forma como você está iterando (cadeia if vs switch).
• Trate .type como o único campo em que você pode confiar antes do "narrowing". Todos os outros campos são específicos de um membro da união.
• Use a tabela de comparação como um guia quando estiver lendo o loop de outra pessoa sobre response.content e precisar saber o que um determinado bloco expõe.
• Lembre-se de que existem duas uniões relacionadas: ContentBlock (o que o Claude envia de volta para você) e os tipos de parâmetro de bloco, como ToolResultBlockParam (o que você envia para o Claude ao construir mensagens). Eles não são intercambiáveis.

Tipos de Bloco de Conteúdo em Resumo

A união que tipa response.content inclui outros membros além desses três para casos menos comuns (atividade de ferramenta no lado do servidor, pensamento redigido e similares). Os três acima são aqueles nos quais um loop típico de tratamento de resposta faz o "narrowing".

TextBlock

TextBlock é o texto comum da resposta do Claude. É o tipo de bloco para o qual você fará "narrowing" com mais frequência.

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: "Diga olá em uma frase." }],
});
 
for (const block of response.content) {
  if (block.type === "text") {
    // O TypeScript agora sabe que `block` é um TextBlock aqui.
    console.log(block.text);
  }
}

ToolUseBlock

ToolUseBlock aparece quando o Claude decide chamar uma das ferramentas que você forneceu. .input é tipado como unknown porque sua forma depende do próprio input_schema da ferramenta, então você ainda precisa validá-lo ou fazer um "cast" antes de usá-lo.

for (const block of response.content) {
  if (block.type === "tool_use") {
    // block.id, block.name, block.input estão todos disponíveis aqui.
    console.log(block.id, block.name, block.input);
  }
}

ThinkingBlock

ThinkingBlock carrega a saída de pensamento estendido do Claude. Ele só aparece em response.content quando o pensamento estendido está ativado para a solicitação; caso contrário, ele simplesmente está ausente, não presente com um valor vazio.

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

Narrowing com uma Instrução switch

Uma cadeia if funciona, mas um switch em block.type é mais legível quando você está lidando com três ou mais tipos de bloco no mesmo loop, e mantém o tipo estreitado de cada ramificação isolado:

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:
      // Outros tipos de bloco na união caem aqui, não estreitados.
      break;
  }
}

Filtrando para um Único Tipo de Bloco

Quando você se importa apenas com um tipo de bloco, filtre primeiro em vez de ramificar dentro do loop. O TypeScript estreita o tipo do elemento do array através de um 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); // nenhum narrowing adicional necessário
}

Tipos de Parâmetro de Bloco São uma União Separada

TextBlock, ToolUseBlock e ThinkingBlock descrevem o que o Claude envia de volta para você. Ao construir mensagens para enviar ao Claude, você usa os tipos de parâmetro correspondentes em vez disso, como ToolResultBlockParam para retornar o resultado de uma ferramenta. Esses tipos de parâmetro não são os mesmos tipos TypeScript dos blocos de resposta, mesmo onde os nomes se sobrepõem, portanto, não reutilize um ToolUseBlock que você recebeu como se fosse conteúdo de entrada válido.

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

FAQs

Relacionados

• O Modelo Mental do SDK TypeScript da Anthropic - como o cliente, as solicitações e as respostas se encaixam antes de você chegar aos tipos de bloco individuais
• Noções Básicas do SDK TypeScript/JavaScript - instalando o SDK e fazendo sua primeira solicitação
• Definições de Ferramentas Fortemente Tipadas com Zod em TypeScript - validando o .input de um ToolUseBlock contra um schema real
• Referência de Classe de Erro do SDK TypeScript - a página de referência correspondente para classes de erro tipadas em vez de blocos de conteúdo
• Tratando Solicitações de Uso de Ferramentas e Retornando Blocos de Resultado de Ferramentas - o ciclo completo de ToolUseBlock para um response ToolResultBlockParam

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial @anthropic-ai/sdk TypeScript (última versão). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.