SDK TypeScript

Esta biblioteca fornece acesso conveniente à Claude API a partir de TypeScript ou JavaScript.

Instalação

npm install @anthropic-ai/sdk

Requisitos

TypeScript >= 4.9 é suportado.

Os seguintes runtimes são suportados:

• Node.js 20 LTS ou versões posteriores (não-EOL).
• Deno v1.28.0 ou superior.
• Bun 1.0 ou posterior.
• Cloudflare Workers.
• Vercel Edge Runtime.
• Jest 28 ou superior com o ambiente "node" ("jsdom" não é suportado no momento).
• Nitro v2.6 ou superior.
• Navegadores web: desabilitado por padrão para evitar expor suas credenciais secretas de API (consulte melhores práticas de chave de API). Habilite o suporte a navegadores definindo explicitamente dangerouslyAllowBrowser como true.

Observe que React Native não é suportado no momento.

Se você tiver interesse em outros ambientes de runtime, abra ou vote em uma issue no repositório do GitHub.

Uso

const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});

const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5"
});

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

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação. Se sua chave de API for uma chave pessoal ou de conta de serviço com acesso a vários workspaces, defina o ID do workspace no cabeçalho de requisição anthropic-workspace-id; Selecionar um workspace mostra a opção por requisição para este SDK.

Tipos de requisição e resposta

Esta biblioteca inclui definições TypeScript para todos os parâmetros de requisição e campos de resposta. Você pode importá-los e usá-los assim:

const client = new Anthropic({
  apiKey: process.env["ANTHROPIC_API_KEY"] // This is the default and can be omitted
});

const params: Anthropic.MessageCreateParams = {
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5"
};
const message: Anthropic.Message = await client.messages.create(params);

A documentação de cada método, parâmetro de requisição e campo de resposta está disponível em docstrings e aparece ao passar o mouse na maioria dos editores modernos.

Contagem de tokens

Você pode ver o uso exato de uma determinada requisição por meio da propriedade de resposta usage, por exemplo:

const message = await client.messages.create(/* ... */);
console.log(message.usage);
// { input_tokens: 25, output_tokens: 13 }

Respostas em streaming

O SDK fornece suporte para respostas em "streaming" (streaming) usando Server Sent Events (SSE).

const client = new Anthropic();

const stream = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5",
  stream: true
});
for await (const messageStreamEvent of stream) {
  console.log(messageStreamEvent.type);
}

Se você precisar cancelar um stream, pode usar break para sair do loop ou chamar stream.controller.abort().

Helpers de streaming

Esta biblioteca fornece várias conveniências para streaming de mensagens, por exemplo:

const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: "Say hello there!"
      }
    ]
  })
  .on("text", (text) => {
    console.log(text);
  });

const message = await stream.finalMessage();
console.log(message);

O streaming com client.messages.stream(...) expõe vários helpers para sua conveniência, incluindo manipuladores de eventos e acumulação.

Alternativamente, você pode usar client.messages.create({ ..., stream: true }), que retorna apenas um iterável assíncrono dos eventos no stream e, portanto, usa menos memória (ele não constrói um objeto de mensagem final para você).

Helpers de ferramentas

Este SDK fornece helpers para facilitar a criação e execução de ferramentas na Messages API. Você pode usar schemas Zod ou JSON Schemas para descrever a entrada de uma ferramenta. Em seguida, você pode executar essas ferramentas usando o método client.beta.messages.toolRunner(). Esse método cuida de passar as entradas geradas pelo modelo escolhido para a ferramenta correta e de passar o resultado de volta ao modelo.

Para mais detalhes sobre "tool use" (uso de ferramentas), consulte Uso de ferramentas com Claude.

import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";

const anthropic = new Anthropic();

const weatherTool = betaZodTool({
  name: "get_weather",
  inputSchema: z.object({
    location: z.string()
  }),
  description: "Get the current weather in a given location",
  run: (input) => {
    return `The weather in ${input.location} is foggy and 60°F`;
  }
});

const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-5",
  max_tokens: 1000,
  messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
  tools: [weatherTool]
});

console.log(finalMessage.content);

Erros de ferramentas

Para reportar um erro de uma ferramenta de volta ao modelo, lance um ToolError a partir da função run. Diferentemente de um Error simples, ToolError aceita blocos de conteúdo, permitindo que você inclua imagens ou outro conteúdo estruturado na resposta de erro:

import { ToolError } from "@anthropic-ai/sdk/lib/tools/BetaRunnableTool";

const screenshotTool = betaZodTool({
  name: "take_screenshot",
  inputSchema: z.object({ url: z.string() }),
  run: async (input) => {
    if (!isValidUrl(input.url)) {
      throw new ToolError(`Invalid URL: ${input.url}`);
    }
    const result = await takeScreenshot(input.url);
    if (result.error) {
      // Inclua a captura de tela do erro para que o modelo possa ver o que deu errado
      throw new ToolError([
        { type: "text", text: `Failed to load page: ${result.error}` },
        {
          type: "image",
          source: { type: "base64", data: result.screenshot, media_type: "image/png" }
        }
      ]);
    }
    return {
      type: "image",
      source: { type: "base64", data: result.screenshot, media_type: "image/png" }
    };
  }
});

Se um Error simples for lançado, a mensagem será convertida em um bloco de conteúdo de texto.

Uso de ferramentas

Este SDK fornece suporte para uso de ferramentas, também conhecido como function calling. Para mais detalhes, consulte Uso de ferramentas com Claude.

Helpers de MCP

Este SDK fornece helpers para integração com servidores Model Context Protocol (MCP). Esses helpers convertem tipos MCP em tipos da Claude API, reduzindo código repetitivo ao trabalhar com ferramentas, prompts e recursos MCP.

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// Conectar a um servidor MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// Usar prompts MCP
const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});
console.log(response.content);

// Usar ferramentas MCP com toolRunner
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Use the available tools" }],
  tools: mcpTools(tools, mcpClient)
});
console.log(finalMessage.content);

// Usar recursos MCP como conteúdo
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// Fazer upload de recursos MCP como arquivos
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });

Tratamento de erros de MCP

As funções de conversão lançam UnsupportedMCPValueError se um valor MCP não for suportado pela Claude API (por exemplo, tipo de conteúdo não suportado, tipo MIME não suportado, link de recurso que não seja http/https).

Lotes de mensagens

Este SDK fornece suporte para processamento em lote no namespace client.messages.batches.

Criando um lote

Message Batches recebe um array de requisições, onde cada objeto tem um identificador custom_id e exatamente os mesmos params de requisição da Messages API padrão:

const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: "my-first-request",
      params: {
        model: "claude-opus-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hello, world" }]
      }
    },
    {
      custom_id: "my-second-request",
      params: {
        model: "claude-opus-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hi again, friend" }]
      }
    }
  ]
});

Obtendo resultados de um lote

Depois que um Message Batch for processado, indicado por .processing_status === 'ended', você pode acessar os resultados com .batches.results()

const results = await client.messages.batches.results(batch.id);
for await (const entry of results) {
  if (entry.result.type === "succeeded") {
    console.log(entry.result.message.content);
  }
}

Upload de arquivos

Parâmetros de requisição que correspondem a uploads de arquivos podem ser passados de várias formas diferentes:

• File (ou um objeto com a mesma estrutura)
• um Response de fetch (ou um objeto com a mesma estrutura)
• um fs.ReadStream
• o valor de retorno do helper toFile

Defina o content-type explicitamente, pois a API de arquivos não o inferirá para você:

import fs from "node:fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";

const client = new Anthropic();

// Se você tiver acesso ao `fs` do Node, use `fs.createReadStream()`:
await client.files.upload({
  file: await toFile(fs.createReadStream("/path/to/file"), undefined, {
    type: "application/json"
  })
});

// Ou, se você tiver a API web `File`, pode passar uma instância de `File`:
await client.files.upload({
  file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// Você também pode passar uma `Response` de `fetch`:
await client.files.upload({
  file: await fetch("https://somesite/file")
});

// Ou um `Buffer` / `Uint8Array`
await client.files.upload({
  file: await toFile(Buffer.from("my bytes"), "file", { type: "text/plain" })
});
await client.files.upload({
  file: await toFile(new Uint8Array([0, 1, 2]), "file", { type: "text/plain" })
});

Tratamento de erros

Quando a biblioteca não consegue se conectar à API, ou se a API retorna um código de status que não indica sucesso (ou seja, resposta 4xx ou 5xx), uma subclasse de APIError é lançada:

const message = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  })
  .catch(async (err) => {
    if (err instanceof Anthropic.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });

Os códigos de erro são os seguintes:

IDs de requisição

Para mais informações sobre depuração de requisições, consulte ID de requisição.

Todas as respostas de objeto no SDK fornecem uma propriedade _request_id, que é adicionada a partir do cabeçalho de resposta request-id, para que você possa registrar rapidamente requisições com falha e reportá-las à Anthropic.

const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5"
});
console.log(message._request_id); // req_018EeWyXxfu5pfWkrYcMdjWG

Novas tentativas

Certos erros são automaticamente repetidos 2 vezes por padrão, com um curto backoff exponencial. Erros de conexão (por exemplo, devido a um problema de conectividade de rede), 408 Request Timeout, 409 Conflict, 429 Rate Limit e erros internos >=500 são todos repetidos por padrão.

Você pode usar a opção maxRetries para configurar ou desabilitar isso:

// Configure o padrão para todas as requisições:
const client = new Anthropic({
  maxRetries: 0 // default is 2
});

// Ou configure por requisição:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  },
  { maxRetries: 5 }
);

Timeouts

Por padrão, as requisições expiram após 10 minutos. No entanto, se você especificou um valor grande de max_tokens e não está usando streaming, o timeout padrão será calculado dinamicamente usando a fórmula:

const minimum = 10 * 60;
const calculated = (60 * 60 * maxTokens) / 128_000;
return calculated < minimum ? minimum * 1000 : calculated * 1000;

o que resultará em um timeout de até 60 minutos, escalado pelo parâmetro max_tokens, a menos que seja sobrescrito no nível da requisição ou do cliente.

Você pode configurar isso com a opção timeout:

// Configure o padrão para todas as requisições:
const client = new Anthropic({
  timeout: 20 * 1000 // 20 seconds (default is 10 minutes)
});

// Substitua por requisição:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  },
  { timeout: 5 * 1000 }
);

Em caso de timeout, um APIConnectionTimeoutError é lançado.

Observe que requisições que expiram são repetidas duas vezes por padrão.

Requisições longas

Evite definir um valor grande de max_tokens sem usar streaming. Algumas redes podem descartar conexões ociosas após um certo período de tempo, o que pode fazer com que a requisição falhe ou atinja o timeout sem receber uma resposta da Anthropic.

Este SDK também lança um erro se for esperado que uma requisição sem streaming dure mais de aproximadamente 10 minutos. Passar stream: true ou sobrescrever a opção timeout no nível do cliente ou da requisição desabilita esse erro.

Uma "latency" (latência) de requisição esperada maior que o timeout para uma requisição sem streaming resultará no cliente encerrando a conexão e tentando novamente sem receber uma resposta.

Quando suportado pela implementação de fetch, o SDK define uma opção de TCP socket keep-alive para reduzir o impacto de timeouts de conexões ociosas em algumas redes. Isso pode ser sobrescrito configurando um proxy personalizado.

Paginação automática

Os métodos de listagem na Claude API são paginados. Você pode usar a sintaxe for await ... of para iterar pelos itens em todas as páginas:

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // Busca automaticamente mais páginas conforme necessário.
  for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
    allMessageBatches.push(messageBatch);
  }
  return allMessageBatches;
}

Alternativamente, você pode solicitar uma única página por vez:

let page = await client.messages.batches.list({ limit: 20 });
for (const messageBatch of page.data) {
  console.log(messageBatch);
}

// Métodos de conveniência são fornecidos para paginação manual:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

Cabeçalhos padrão

O SDK envia automaticamente o cabeçalho anthropic-version definido como 2023-06-01.

Se necessário, você pode sobrescrevê-lo definindo cabeçalhos padrão por requisição.

Esteja ciente de que fazer isso pode resultar em tipos incorretos e outros comportamentos inesperados ou indefinidos no SDK.

const client = new Anthropic();

const message = await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);

Uso avançado

Acessando dados brutos de Response (por exemplo, cabeçalhos)

O Response "bruto" retornado por fetch() pode ser acessado por meio do método .asResponse() no tipo APIPromise que todos os métodos retornam. Esse método retorna assim que os cabeçalhos de uma resposta bem-sucedida são recebidos e não consome o corpo da resposta, então você fica livre para escrever lógica personalizada de parsing ou streaming.

Você também pode usar o método .withResponse() para obter o Response bruto junto com os dados analisados. Diferentemente de .asResponse(), esse método consome o corpo, retornando assim que ele é analisado.

const client = new Anthropic();

const response = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  })
  .asResponse();
console.log(response.headers.get("X-My-Header"));
console.log(response.statusText); // access the underlying Response object

const { data: message, response: raw } = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  })
  .withResponse();
console.log(raw.headers.get("X-My-Header"));
console.log(message.content);

Logging

Níveis de log

Você pode configurar o nível de log de duas maneiras:

1. Por meio da variável de ambiente ANTHROPIC_LOG
2. Usando a opção de cliente logLevel (sobrescreve a variável de ambiente, se definida)

const client = new Anthropic({
  logLevel: "debug" // Show all log messages
});

Níveis de log disponíveis, do mais ao menos verboso:

• 'debug' - Mostra mensagens de debug, info, avisos e erros
• 'info' - Mostra mensagens de info, avisos e erros
• 'warn' - Mostra avisos e erros (padrão)
• 'error' - Mostra apenas erros
• 'off' - Desabilita todo o logging

No nível 'debug', todas as requisições e respostas HTTP são registradas, incluindo cabeçalhos e corpos. Alguns cabeçalhos relacionados à autenticação são ocultados, mas dados sensíveis nos corpos de requisição e resposta ainda podem ficar visíveis.

Logger personalizado

Por padrão, esta biblioteca registra logs em globalThis.console. Você também pode fornecer um logger personalizado. A maioria das bibliotecas de logging é suportada, incluindo pino, winston, bunyan, consola, signale e @std/log. Se o seu logger não funcionar, abra uma issue.

Ao fornecer um logger personalizado, a opção logLevel ainda controla quais mensagens são emitidas; mensagens abaixo do nível configurado não serão enviadas ao seu logger.

import pino from "pino";

const logger = pino();

const client = new Anthropic({
  logger: logger.child({ name: "Anthropic" }),
  logLevel: "debug" // Send all messages to pino, allowing it to filter
});

Fazendo requisições personalizadas/não documentadas

Esta biblioteca é tipada para acesso conveniente à API documentada. Se você precisar acessar endpoints, parâmetros ou propriedades de resposta não documentados, a biblioteca ainda pode ser usada.

Endpoints não documentados

Para fazer requisições a endpoints não documentados, você pode usar client.get, client.post e outros verbos HTTP. As opções do cliente, como novas tentativas, são respeitadas ao fazer essas requisições.

await client.post("/some/path", {
  body: { some_prop: "foo" },
  query: { some_query_arg: "bar" }
});

Parâmetros de requisição não documentados

Para fazer requisições usando parâmetros não documentados, você pode usar // @ts-expect-error no parâmetro não documentado. Esta biblioteca não valida em tempo de execução se a requisição corresponde ao tipo, então quaisquer valores extras que você enviar serão enviados como estão.

client.messages.create({
  // ...
  // @ts-expect-error baz is not yet public
  baz: "undocumented option"
});

Para requisições com o verbo GET, quaisquer parâmetros extras estarão na query; todas as outras requisições enviarão o parâmetro extra no corpo.

Se você quiser enviar explicitamente um argumento extra, pode fazê-lo com as opções de requisição query, body e headers.

Propriedades de resposta não documentadas

Para acessar propriedades de resposta não documentadas, você pode acessar o objeto de resposta com // @ts-expect-error no objeto de resposta, ou fazer cast do objeto de resposta para o tipo necessário. Assim como nos parâmetros de requisição, o SDK não valida nem remove propriedades extras da resposta da API.

Personalizando o cliente fetch

Por padrão, esta biblioteca espera que uma função global fetch esteja definida.

Se você quiser usar uma função fetch diferente, pode fazer polyfill da global:

import fetch from "my-fetch";

globalThis.fetch = fetch;

Ou passá-la para o cliente:

import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Opções de fetch

Se você quiser definir opções personalizadas de fetch sem sobrescrever a função fetch, pode fornecer um objeto fetchOptions ao criar o cliente ou ao fazer uma requisição. (Opções específicas da requisição sobrescrevem as opções do cliente.)

const client = new Anthropic({
  fetchOptions: {
    // opções de `RequestInit`
  }
});

Configurando proxies

Para modificar o comportamento de proxy, você pode fornecer fetchOptions personalizadas que adicionam opções de proxy específicas do runtime às requisições:

import * as undici from "undici";

const proxyAgent = new undici.ProxyAgent("http://localhost:8888");
const client = new Anthropic({
  fetchOptions: {
    dispatcher: proxyAgent
  }
});

Recursos beta

Recursos beta estão disponíveis antes do lançamento geral para obter feedback antecipado e testar novas funcionalidades. Você pode verificar a disponibilidade de todas as capacidades e ferramentas do Claude na visão geral de construir com Claude.

Você pode acessar a maioria dos recursos beta da API por meio da propriedade beta do cliente. Para habilitar um recurso beta específico, você precisa adicionar o cabeçalho beta apropriado ao campo betas ao criar uma mensagem.

Por exemplo, para habilitar a edição de contexto:

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  betas: ["context-management-2025-06-27"]
});

Suporte a runtimes

Integrações com plataformas

O SDK TypeScript suporta as seguintes plataformas:

• Agent Platform: npm install @anthropic-ai/vertex-sdk: Fornece o cliente AnthropicVertex
• Bedrock: npm install @anthropic-ai/bedrock-sdk: Fornece o cliente AnthropicBedrockMantle, e AnthropicBedrock para o caminho bedrock-runtime
• Claude Platform on AWS: npm install @anthropic-ai/aws-sdk: Fornece o cliente AnthropicAws. Passe workspaceId para o construtor ou defina a variável de ambiente ANTHROPIC_AWS_WORKSPACE_ID. Disponível em beta.
• Foundry: npm install @anthropic-ai/foundry-sdk: Fornece o cliente AnthropicFoundry

Use AnthropicBedrockMantle para novos projetos; AnthropicBedrock permanece para aplicações existentes que usam a API InvokeModel do Bedrock.

Versionamento semântico

Este pacote geralmente segue as convenções do SemVer, embora certas mudanças incompatíveis com versões anteriores possam ser lançadas como versões minor:

1. Mudanças que afetam apenas tipos estáticos, sem quebrar o comportamento em tempo de execução.
2. Mudanças em partes internas da biblioteca que são tecnicamente públicas, mas não destinadas ou documentadas para uso externo.
3. Mudanças que não devem impactar a grande maioria dos usuários na prática.

A compatibilidade com versões anteriores é levada a sério para garantir que você possa contar com uma experiência de atualização tranquila.

Perguntas frequentes

Consulte o repositório do GitHub para FAQs, issues e suporte da comunidade.

Recursos adicionais

• Repositório do GitHub
• Referência da API
• Streaming de mensagens
• Uso de ferramentas com Claude