SDK para TypeScript

Esta biblioteca fornece acesso conveniente à API REST da Anthropic 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 para chaves de API). Habilite o suporte a navegador definindo explicitamente dangerouslyAllowBrowser como true.

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

Se você estiver interessado em outros ambientes de runtime, abra ou vote em uma issue no 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-4-8"
});

console.log(message.content);

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação.

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-4-8"
};
const message: Anthropic.Message = await client.messages.create(params);

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

Contagem de tokens

Você pode ver o uso exato de uma determinada requisição através 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 usando "Server Sent Events" (eventos enviados pelo servidor), ou SSE.

const client = new Anthropic();

const stream = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-4-8",
  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-4-8",
    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 (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. Você pode então executar essas ferramentas usando o método client.beta.messages.toolRunner(). Esse método cuidará de passar as entradas geradas pelo modelo escolhido para a ferramenta correta e de passar o resultado de volta para o modelo.

Para mais detalhes sobre 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-4-8",
  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 comum, 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 veja 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 comum for lançado, a mensagem será convertida em um bloco de conteúdo de texto.

Uso de ferramentas

Este SDK fornece suporte para "tool use" (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 API do Claude, 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 do MCP
const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});
console.log(response.content);

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

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

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

Tratamento de erros MCP

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

Lotes de mensagens

Este SDK fornece suporte para a Message Batches API sob o 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 que a Messages API padrão:

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

Obtendo resultados de um lote

Uma vez que um Message Batch tenha sido 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)
• uma Response do 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 files API não o inferirá para você:

import fs from "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.beta.files.upload({
  file: await toFile(fs.createReadStream("/path/to/file"), undefined, {
    type: "application/json"
  })
});

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

// Ou um `Buffer` / `Uint8Array`
await client.beta.files.upload({
  file: await toFile(Buffer.from("my bytes"), "file", { type: "text/plain" })
});
await client.beta.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 de não-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-4-8"
  })
  .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 Request ID.

Todas as respostas de objeto no SDK fornecem uma propriedade _request_id que é adicionada a partir do header 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-4-8"
});
console.log(message._request_id); // req_018EeWyXxfu5pfWkrYcMdjWG

Retentativas

Certos erros serão automaticamente retentados 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 retentados 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-4-8"
  },
  { 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 substituído no nível da requisição ou do cliente.

Você pode configurar isso com uma 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-4-8"
  },
  { timeout: 5 * 1000 }
);

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

Observe que requisições que expiram serão retentadas 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 expire sem receber uma resposta da Anthropic.

Este SDK também lançará um erro se uma requisição sem streaming tiver previsão de durar mais de aproximadamente 10 minutos. Passar stream: true ou substituir a opção timeout no nível do cliente ou da requisição desabilita esse erro.

Uma latência de requisição esperada maior que o timeout para uma requisição sem streaming resultará no cliente encerrando a conexão e retentando 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ão ociosa em algumas redes. Isso pode ser substituído configurando um proxy personalizado.

Paginação automática

Métodos de listagem na API do Claude 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();
  // ...
}

Headers padrão

O SDK envia automaticamente o header anthropic-version definido como 2023-06-01.

Se necessário, você pode substituí-lo definindo headers 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-4-8"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);

Uso avançado

Acessando dados brutos de Response (por exemplo, headers)

A Response "bruta" retornada por fetch() pode ser acessada através do método .asResponse() no tipo APIPromise que todos os métodos retornam. Esse método retorna assim que os headers 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 a Response bruta junto com os dados parseados. Diferentemente de .asResponse(), esse método consome o corpo, retornando assim que ele é parseado.

const client = new Anthropic();

const response = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-8"
  })
  .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-4-8"
  })
  .withResponse();
console.log(raw.headers.get("X-My-Header"));
console.log(message.content);

Logging

Níveis de log

O nível de log pode ser configurado de duas maneiras:

1. Via a variável de ambiente ANTHROPIC_LOG
2. Usando a opção de cliente logLevel (substitui 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 headers e corpos. Alguns headers relacionados à autenticação são redigidos, mas dados sensíveis nos corpos de requisição e resposta ainda podem estar 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. Opções no cliente, como retentativas, serã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 os 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 fetch global 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 substituir a função fetch, pode fornecer um objeto fetchOptions ao criar o cliente ou fazer uma requisição. (Opções específicas de requisição substituem 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:

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 através da propriedade beta do cliente. Para habilitar um recurso beta específico, você precisa adicionar o header beta apropriado ao campo betas ao criar uma mensagem.

Por exemplo, para usar a Files API:

const client = new Anthropic();
const response = await client.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Please summarize this document for me." },
        {
          type: "document",
          source: {
            type: "file",
            file_id: "file_abc123"
          }
        }
      ]
    }
  ],
  betas: ["files-api-2025-04-14"]
});

Suporte a runtimes

Integrações de plataforma

O SDK TypeScript suporta as seguintes plataformas:

• Bedrock: npm install @anthropic-ai/bedrock-sdk: Fornece o cliente AnthropicBedrockMantle, e AnthropicBedrock para o caminho bedrock-runtime
• Vertex AI: npm install @anthropic-ai/vertex-sdk: Fornece o cliente AnthropicVertex
• Foundry: npm install @anthropic-ai/foundry-sdk: Fornece o cliente AnthropicFoundry
• Claude Platform na 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.

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 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 internos da biblioteca que são tecnicamente públicos, mas não destinados ou documentados para uso externo.
3. Mudanças que não se espera que impactem 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 no GitHub para FAQs, issues e suporte da comunidade.

Recursos adicionais

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