Noções Básicas do SDK TypeScript/JavaScript

11 exemplos para você começar com o SDK TypeScript/JavaScript, 7 básicos e 4 intermediários.

Pré-requisitos / Instalação Rápida

Node.js 18+ (ou um runtime de edge como Vercel Edge, Cloudflare Workers ou Deno Deploy, já que o SDK é baseado em fetch).
Instale o pacote: npm install @anthropic-ai/sdk.
Uma chave de API do Claude Console, configurada como a variável de ambiente ANTHROPIC_API_KEY.
TypeScript 5+ recomendado para que você obtenha os tipos embutidos do SDK sem configuração adicional.

Exemplos Básicos

1. Instale o Pacote

Adicione o SDK oficial ao seu projeto com o gerenciador de pacotes de sua preferência.

npm install @anthropic-ai/sdk

O SDK envia seus próprios tipos TypeScript, portanto, nenhum pacote @types separado é necessário.
Ele é baseado em fetch internamente, é por isso que roda sem modificações no Node.js e em runtimes de edge.
Funciona com npm, pnpm, yarn ou bun, já que é publicado como um pacote npm padrão.

2. Configure a Chave de API via Variável de Ambiente

Armazene sua chave de API fora do seu código-fonte e deixe o cliente pegá-la automaticamente.

# .env.local (nunca comite este arquivo)
ANTHROPIC_API_KEY=sk-ant-...

O SDK lê process.env.ANTHROPIC_API_KEY por padrão, então raramente você precisará passar uma chave explicitamente no código.
Manter a chave em uma variável de ambiente evita vazá-la no controle de versão ou em bundles do lado do cliente.
No Next.js, referencie esta variável apenas a partir de código do lado do servidor (route handlers, server actions), nunca em componentes do cliente.
Use um gerenciador de segredos ou as configurações de variável de ambiente do seu provedor de hospedagem em produção em vez de um arquivo .env comitado.

3. Instancie o Cliente

Crie uma instância do cliente Anthropic uma vez e reutilize-a entre as requisições.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
// Lê ANTHROPIC_API_KEY de process.env automaticamente

new Anthropic() sem argumentos pega ANTHROPIC_API_KEY do ambiente.
Você pode substituir a chave explicitamente com new Anthropic({ apiKey: "..." }) se estiver carregando-a de uma fonte de segredos personalizada.
Crie o cliente uma vez no escopo do módulo e importe-o onde for necessário, em vez de construir uma nova instância por requisição.
O mesmo cliente funciona em runtimes Node.js e de edge sem qualquer configuração condicional.

Relacionado: O Modelo Mental do SDK TypeScript da Anthropic - como o cliente e seu transporte baseado em fetch se encaixam

4. Envie uma Mensagem Básica

Chame client.messages.create() para obter uma resposta única e não transmitida do Claude.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Explique o que é um closure em uma frase." }],
});
 
console.log(message.content);

model, max_tokens e messages são os campos obrigatórios para uma chamada messages.create().
claude-sonnet-5 é o modelo padrão na linha atual do Claude e um bom ponto de partida para a maioria das tarefas.
A chamada retorna uma promessa, então ela deve ser aguardada (ou tratada com .then()).
message.content é um array de blocos de conteúdo, não uma string simples, já que uma resposta pode misturar texto, chamadas de ferramentas e outros tipos de blocos.

Relacionado: Referência de Tipos do SDK TypeScript para Blocos de Conteúdo - o que está realmente dentro desse array de conteúdo

5. Leia a Resposta Tipada

Restrinja os blocos de conteúdo da resposta usando os tipos de união discriminados do SDK.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Diga olá em três idiomas." }],
});
 
for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

Cada bloco de conteúdo tem um discriminador type ("text", "tool_use", "thinking", e assim por diante), que o TypeScript usa para restringir o tipo.
Verificar block.type === "text" antes de ler block.text oferece segurança em tempo de compilação em vez de uma suposição com tipo any.
O tipo de resposta também inclui usage, stop_reason e role, todos totalmente tipados.
Este padrão escala diretamente para respostas de uso de ferramentas, onde você verificaria block.type === "tool_use" em vez disso.

6. Mantenha uma Conversa Multi-Turno

Construa o array messages ao longo dos turnos para dar ao Claude o histórico da conversa.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const history: Anthropic.MessageParam[] = [
  { role: "user", content: "Qual é a capital da França?" },
  { role: "assistant", content: "A capital da França é Paris." },
  { role: "user", content: "Qual é a sua população?" },
];
 
const reply = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 512,
  messages: history,
});

Anthropic.MessageParam é o tipo exportado para uma única entrada de mensagem, útil para tipar arrays que você constrói ao longo do tempo.
O Claude não tem memória de servidor para turnos anteriores; a conversa completa deve ser reenviada como messages em cada chamada.
As funções alternam entre "user" e "assistant", e o array geralmente deve começar com uma mensagem "user".
Anexe o texto de cada nova resposta a history antes da próxima chamada para manter a conversa crescendo corretamente.

7. Defina um Prompt do Sistema e um Limite de Tokens

Direcione o comportamento do Claude com um prompt system, separado da conversa em si.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 256,
  system: "Você é um assistente conciso. Responda em uma única frase.",
  messages: [{ role: "user", content: "Por que o céu é azul?" }],
});

system é um parâmetro de nível superior, não uma mensagem com a função "system", e se aplica a toda a requisição.
max_tokens limita o comprimento da resposta do Claude e conta contra seu uso, portanto, defina-o para o que a tarefa realmente precisa.
Reduzir max_tokens agressivamente demais pode cortar uma resposta no meio do pensamento; verifique stop_reason na resposta se as respostas parecerem truncadas.
Troque claude-sonnet-5 por claude-haiku-4-5 em caminhos sensíveis à latência ou claude-opus-4-8 para as tarefas de raciocínio mais difíceis.

Exemplos Intermediários

8. Transmita uma Resposta com Iteradores Assíncronos

Consuma tokens à medida que chegam, em vez de esperar pela resposta completa.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Escreva um haicai sobre bancos de dados." }],
});
 
for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

client.messages.stream() retorna um iterador assíncrono, então for await consome eventos sem a necessidade de configurar manualmente listeners de eventos.
Cada evento é tipado e discriminado por event.type, espelhando o padrão usado para blocos de conteúdo.
O stream também expõe métodos auxiliares como .finalMessage() se você quiser o resultado montado após o término do loop.
Prefira streaming para qualquer coisa renderizada ao vivo em uma interface de usuário; use messages.create() quando você só precisar do texto final.

Relacionado: Iteradores Assíncronos para Streaming no SDK TypeScript - uma análise mais aprofundada do consumo de eventos de stream

9. Capture Erros Tipados

Trate falhas de API com as classes de erro específicas do SDK em vez de um catch-all genérico.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
try {
  await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Olá" }],
  });
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    console.warn("Limite de taxa atingido, aguarde e tente novamente.");
  } else if (error instanceof Anthropic.APIConnectionError) {
    console.error("Problema de rede ao alcançar a API.");
  } else {
    throw error;
  }
}

Classes de erro como RateLimitError, BadRequestError e APIConnectionError permitem que você ramifique com instanceof com estreitamento de tipo completo.
Cada erro carrega um código de status e detalhes da resposta, úteis para log ou para exibir uma mensagem específica aos usuários.
Relançar erros desconhecidos (o ramo else) evita engolir silenciosamente bugs que você não antecipou.
Este padrão vale a pena ser encapsulado em um helper compartilhado assim que você tiver mais de um ou dois pontos de chamada.

Relacionado: Referência de Classes de Erro do SDK TypeScript - a lista completa de classes de erro e quando cada uma delas dispara

10. Configure Retentativas, Timeouts e Cancelamento

Ajuste as configurações de resiliência e cancele requisições em andamento com AbortController.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic({
  maxRetries: 3,
  timeout: 20_000,
});
 
const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);
 
const message = await client.messages.create(
  {
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Resuma isto em uma linha." }],
  },
  { signal: controller.signal }
);

maxRetries e timeout são padrões em nível de cliente; ambos também podem ser substituídos por requisição.
Passar o signal de um AbortController como uma opção de requisição permite cancelar uma chamada a partir da interação do usuário (como um botão "Parar de gerar").
Isso funciona da mesma forma em ambientes Node e de navegador, já que ambos implementam a API padrão AbortController.
As retentativas só entram em vigor para falhas que podem ser retentadas (como erros de rede transitórios ou limites de taxa), não para erros de validação.

Relacionado: Padrões de Retentativa, Timeout e AbortController no SDK TypeScript - ajuste de backoff e cancelamento com mais detalhes

11. Execute o Mesmo Cliente em um Runtime de Edge

Use o código do cliente idêntico em uma Vercel Edge Function, Cloudflare Worker ou servidor Node.

export const runtime = "edge";
 
import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
export async function POST(request: Request) {
  const { prompt } = await request.json();
 
  const message = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 512,
    messages: [{ role: "user", content: prompt }],
  });
 
  return Response.json(message);
}

Como o SDK é construído sobre fetch, este route handler não precisa de APIs específicas do Node e roda sem modificações sob export const runtime = "edge".
A mesma chamada new Anthropic() funciona se o código for executado no Node.js, Vercel Edge, Cloudflare Workers ou Deno Deploy.
Runtimes de edge geralmente têm limites mais rígidos de memória e tempo de execução, portanto, mantenha max_tokens e qualquer loop de streaming ciente disso.
Variáveis de ambiente como ANTHROPIC_API_KEY ainda precisam ser configuradas especificamente para o ambiente de edge, pois é um runtime separado da sua implantação Node.

Relacionado: Executando o SDK Anthropic em Runtimes de Edge - configuração e armadilhas específicas de edge | Definições de Ferramentas Fortemente Tipadas com Zod em TypeScript - tipando chamadas de ferramentas quando você vai além de mensagens de texto simples

Versões da Pilha: Escrito contra a linha de modelos Claude atualizada 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.

Noções Básicas do SDK TypeScript/JavaScript

11 exemplos para você começar com o SDK TypeScript/JavaScript, 7 básicos e 4 intermediários.

Pré-requisitos / Instalação Rápida

Node.js 18+ (ou um runtime de edge como Vercel Edge, Cloudflare Workers ou Deno Deploy, já que o SDK é baseado em fetch).
Instale o pacote: npm install @anthropic-ai/sdk.
Uma chave de API do Claude Console, configurada como a variável de ambiente ANTHROPIC_API_KEY.
TypeScript 5+ recomendado para que você obtenha os tipos embutidos do SDK sem configuração adicional.

Exemplos Básicos

1. Instale o Pacote

Adicione o SDK oficial ao seu projeto com o gerenciador de pacotes de sua preferência.

npm install @anthropic-ai/sdk

O SDK envia seus próprios tipos TypeScript, portanto, nenhum pacote @types separado é necessário.
Ele é baseado em fetch internamente, é por isso que roda sem modificações no Node.js e em runtimes de edge.
Funciona com npm, pnpm, yarn ou bun, já que é publicado como um pacote npm padrão.

2. Configure a Chave de API via Variável de Ambiente

Armazene sua chave de API fora do seu código-fonte e deixe o cliente pegá-la automaticamente.

# .env.local (nunca comite este arquivo)
ANTHROPIC_API_KEY=sk-ant-...

O SDK lê process.env.ANTHROPIC_API_KEY por padrão, então raramente você precisará passar uma chave explicitamente no código.
Manter a chave em uma variável de ambiente evita vazá-la no controle de versão ou em bundles do lado do cliente.
No Next.js, referencie esta variável apenas a partir de código do lado do servidor (route handlers, server actions), nunca em componentes do cliente.
Use um gerenciador de segredos ou as configurações de variável de ambiente do seu provedor de hospedagem em produção em vez de um arquivo .env comitado.

3. Instancie o Cliente

Crie uma instância do cliente Anthropic uma vez e reutilize-a entre as requisições.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
// Lê ANTHROPIC_API_KEY de process.env automaticamente

new Anthropic() sem argumentos pega ANTHROPIC_API_KEY do ambiente.
Você pode substituir a chave explicitamente com new Anthropic({ apiKey: "..." }) se estiver carregando-a de uma fonte de segredos personalizada.
Crie o cliente uma vez no escopo do módulo e importe-o onde for necessário, em vez de construir uma nova instância por requisição.
O mesmo cliente funciona em runtimes Node.js e de edge sem qualquer configuração condicional.

Relacionado: O Modelo Mental do SDK TypeScript da Anthropic - como o cliente e seu transporte baseado em fetch se encaixam

4. Envie uma Mensagem Básica

Chame client.messages.create() para obter uma resposta única e não transmitida do Claude.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Explique o que é um closure em uma frase." }],
});
 
console.log(message.content);

model, max_tokens e messages são os campos obrigatórios para uma chamada messages.create().
claude-sonnet-5 é o modelo padrão na linha atual do Claude e um bom ponto de partida para a maioria das tarefas.
A chamada retorna uma promessa, então ela deve ser aguardada (ou tratada com .then()).
message.content é um array de blocos de conteúdo, não uma string simples, já que uma resposta pode misturar texto, chamadas de ferramentas e outros tipos de blocos.

Relacionado: Referência de Tipos do SDK TypeScript para Blocos de Conteúdo - o que está realmente dentro desse array de conteúdo

5. Leia a Resposta Tipada

Restrinja os blocos de conteúdo da resposta usando os tipos de união discriminados do SDK.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Diga olá em três idiomas." }],
});
 
for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

Cada bloco de conteúdo tem um discriminador type ("text", "tool_use", "thinking", e assim por diante), que o TypeScript usa para restringir o tipo.
Verificar block.type === "text" antes de ler block.text oferece segurança em tempo de compilação em vez de uma suposição com tipo any.
O tipo de resposta também inclui usage, stop_reason e role, todos totalmente tipados.
Este padrão escala diretamente para respostas de uso de ferramentas, onde você verificaria block.type === "tool_use" em vez disso.

6. Mantenha uma Conversa Multi-Turno

Construa o array messages ao longo dos turnos para dar ao Claude o histórico da conversa.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const history: Anthropic.MessageParam[] = [
  { role: "user", content: "Qual é a capital da França?" },
  { role: "assistant", content: "A capital da França é Paris." },
  { role: "user", content: "Qual é a sua população?" },
];
 
const reply = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 512,
  messages: history,
});

Anthropic.MessageParam é o tipo exportado para uma única entrada de mensagem, útil para tipar arrays que você constrói ao longo do tempo.
O Claude não tem memória de servidor para turnos anteriores; a conversa completa deve ser reenviada como messages em cada chamada.
As funções alternam entre "user" e "assistant", e o array geralmente deve começar com uma mensagem "user".
Anexe o texto de cada nova resposta a history antes da próxima chamada para manter a conversa crescendo corretamente.

7. Defina um Prompt do Sistema e um Limite de Tokens

Direcione o comportamento do Claude com um prompt system, separado da conversa em si.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 256,
  system: "Você é um assistente conciso. Responda em uma única frase.",
  messages: [{ role: "user", content: "Por que o céu é azul?" }],
});

system é um parâmetro de nível superior, não uma mensagem com a função "system", e se aplica a toda a requisição.
max_tokens limita o comprimento da resposta do Claude e conta contra seu uso, portanto, defina-o para o que a tarefa realmente precisa.
Reduzir max_tokens agressivamente demais pode cortar uma resposta no meio do pensamento; verifique stop_reason na resposta se as respostas parecerem truncadas.
Troque claude-sonnet-5 por claude-haiku-4-5 em caminhos sensíveis à latência ou claude-opus-4-8 para as tarefas de raciocínio mais difíceis.

Exemplos Intermediários

8. Transmita uma Resposta com Iteradores Assíncronos

Consuma tokens à medida que chegam, em vez de esperar pela resposta completa.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Escreva um haicai sobre bancos de dados." }],
});
 
for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

client.messages.stream() retorna um iterador assíncrono, então for await consome eventos sem a necessidade de configurar manualmente listeners de eventos.
Cada evento é tipado e discriminado por event.type, espelhando o padrão usado para blocos de conteúdo.
O stream também expõe métodos auxiliares como .finalMessage() se você quiser o resultado montado após o término do loop.
Prefira streaming para qualquer coisa renderizada ao vivo em uma interface de usuário; use messages.create() quando você só precisar do texto final.

Relacionado: Iteradores Assíncronos para Streaming no SDK TypeScript - uma análise mais aprofundada do consumo de eventos de stream

9. Capture Erros Tipados

Trate falhas de API com as classes de erro específicas do SDK em vez de um catch-all genérico.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
try {
  await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Olá" }],
  });
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    console.warn("Limite de taxa atingido, aguarde e tente novamente.");
  } else if (error instanceof Anthropic.APIConnectionError) {
    console.error("Problema de rede ao alcançar a API.");
  } else {
    throw error;
  }
}

Classes de erro como RateLimitError, BadRequestError e APIConnectionError permitem que você ramifique com instanceof com estreitamento de tipo completo.
Cada erro carrega um código de status e detalhes da resposta, úteis para log ou para exibir uma mensagem específica aos usuários.
Relançar erros desconhecidos (o ramo else) evita engolir silenciosamente bugs que você não antecipou.
Este padrão vale a pena ser encapsulado em um helper compartilhado assim que você tiver mais de um ou dois pontos de chamada.

Relacionado: Referência de Classes de Erro do SDK TypeScript - a lista completa de classes de erro e quando cada uma delas dispara

10. Configure Retentativas, Timeouts e Cancelamento

Ajuste as configurações de resiliência e cancele requisições em andamento com AbortController.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic({
  maxRetries: 3,
  timeout: 20_000,
});
 
const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);
 
const message = await client.messages.create(
  {
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Resuma isto em uma linha." }],
  },
  { signal: controller.signal }
);

maxRetries e timeout são padrões em nível de cliente; ambos também podem ser substituídos por requisição.
Passar o signal de um AbortController como uma opção de requisição permite cancelar uma chamada a partir da interação do usuário (como um botão "Parar de gerar").
Isso funciona da mesma forma em ambientes Node e de navegador, já que ambos implementam a API padrão AbortController.
As retentativas só entram em vigor para falhas que podem ser retentadas (como erros de rede transitórios ou limites de taxa), não para erros de validação.

Relacionado: Padrões de Retentativa, Timeout e AbortController no SDK TypeScript - ajuste de backoff e cancelamento com mais detalhes

11. Execute o Mesmo Cliente em um Runtime de Edge

Use o código do cliente idêntico em uma Vercel Edge Function, Cloudflare Worker ou servidor Node.

export const runtime = "edge";
 
import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
export async function POST(request: Request) {
  const { prompt } = await request.json();
 
  const message = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 512,
    messages: [{ role: "user", content: prompt }],
  });
 
  return Response.json(message);
}

Como o SDK é construído sobre fetch, este route handler não precisa de APIs específicas do Node e roda sem modificações sob export const runtime = "edge".
A mesma chamada new Anthropic() funciona se o código for executado no Node.js, Vercel Edge, Cloudflare Workers ou Deno Deploy.
Runtimes de edge geralmente têm limites mais rígidos de memória e tempo de execução, portanto, mantenha max_tokens e qualquer loop de streaming ciente disso.
Variáveis de ambiente como ANTHROPIC_API_KEY ainda precisam ser configuradas especificamente para o ambiente de edge, pois é um runtime separado da sua implantação Node.

Relacionado: Executando o SDK Anthropic em Runtimes de Edge - configuração e armadilhas específicas de edge | Definições de Ferramentas Fortemente Tipadas com Zod em TypeScript - tipando chamadas de ferramentas quando você vai além de mensagens de texto simples

Versões da Pilha: Escrito contra a linha de modelos Claude atualizada 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.

Noções Básicas do SDK TypeScript/JavaScript

Buscar na documentação

Noções Básicas do SDK TypeScript/JavaScript