---
title: TypeScript SDK
url: https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/typescript
description: Instale e configure o SDK TypeScript da Anthropic para ambientes Node.js, Deno, Bun e navegador
---

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

<Info>
  Para documentação de recursos da API com exemplos de código, consulte a [referência da API](https://platform.claude.com/docs/pt-BR/api/overview). Esta página aborda recursos e configurações do SDK específicos do TypeScript.
</Info>

## Instalação

```bash
npm install @anthropic-ai/sdk
```

## Requisitos

TypeScript >= 5.0 é suportado.

Os seguintes runtimes são suportados:

* Node.js 20 LTS ou versões posteriores ([sem EOL](https://endoflife.date/nodejs)).
* 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 da API (consulte [práticas recomendadas para chaves de API](https://support.claude.com/en/articles/9767949-api-key-best-practices-keeping-your-keys-safe-and-secure)). Habilite o suporte a navegadores definindo explicitamente `dangerouslyAllowBrowser` como `true`.

Observe que o 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](https://github.com/anthropics/anthropic-sdk-typescript).

## Uso

```typescript
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-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](https://platform.claude.com/docs/pt-BR/manage-claude/authentication). Se a sua chave de API for uma [chave pessoal ou de conta de serviço](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#key-types) que não esteja vinculada a um workspace, defina o ID do workspace no cabeçalho de requisição `anthropic-workspace-id`; [Selecionar um workspace](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#select-a-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:

```typescript
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-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:

```typescript
const message = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5-5"
});
console.log(message.usage);
// { input_tokens: 25, output_tokens: 13 }
```

## Respostas em streaming

O SDK oferece suporte a respostas em "streaming" (streaming) usando Server-Sent Events (SSE).

```typescript
const client = new Anthropic();

const stream = await client.messages.create({
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
  model: "claude-opus-5-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()`.

## Auxiliares de streaming

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

```typescript
const anthropic = new Anthropic();

const stream = anthropic.messages
  .stream({
    model: "claude-opus-5-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 auxiliares 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ê).

## Auxiliares de ferramentas

Este SDK fornece auxiliares 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 devolver o resultado ao modelo.

Para mais detalhes sobre "tool use" (uso de ferramentas), consulte [Uso de ferramentas com Claude](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview). Para executar a ferramenta de uso do navegador ou a ferramenta de uso do computador com este SDK, consulte [Uso do navegador e do computador com os toolsets do SDK](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-sdk).

```typescript
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-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 incluir imagens ou outro conteúdo estruturado na resposta de erro:

```typescript
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` simples for lançado, a mensagem será convertida em um bloco de conteúdo de texto.

## Uso de ferramentas

Este SDK oferece suporte ao uso de ferramentas, também conhecido como function calling. Para mais detalhes, consulte [Uso de ferramentas com Claude](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview).

## Auxiliares de MCP

Este SDK fornece auxiliares para integração com servidores "Model Context Protocol", ou [MCP](https://modelcontextprotocol.io/). Esses auxiliares convertem tipos MCP em tipos da Claude API, reduzindo o código repetitivo ao trabalhar com ferramentas, prompts e recursos MCP.

<Tip>
  A Claude API também oferece suporte a um [parâmetro `mcp_servers`](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector) que permite que Claude se conecte diretamente a servidores MCP remotos. Use `mcp_servers` quando você tiver servidores remotos acessíveis por URL e precisar apenas de suporte a ferramentas. Use os auxiliares de MCP quando precisar de servidores MCP locais, prompts, recursos ou mais controle sobre a conexão MCP.
</Tip>

```typescript
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-5-5",
  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-5-5",
  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-5-5",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// Enviar recursos do 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 oferece suporte a [Processamento em lote](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing) no namespace `client.messages.batches`.

### Criando um lote

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

```typescript
const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: "my-first-request",
      params: {
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "Hello, world" }]
      }
    },
    {
      custom_id: "my-second-request",
      params: {
        model: "claude-opus-5-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()`

```typescript
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` do `fetch` (ou um objeto com a mesma estrutura)
* um `fs.ReadStream`
* o valor de retorno do auxiliar `toFile`

Defina o tipo de conteúdo explicitamente, pois a Files API não o inferirá para você:

```typescript
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 um `Response` do `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 de falha (ou seja, resposta 4xx ou 5xx), uma subclasse de `APIError` é lançada:

```typescript
const message = await client.messages
  .create({
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-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:

| Código de status | Tipo de erro               |
| ---------------- | -------------------------- |
| 400              | `BadRequestError`          |
| 401              | `AuthenticationError`      |
| 403              | `PermissionDeniedError`    |
| 404              | `NotFoundError`            |
| 409              | `ConflictError`            |
| 422              | `UnprocessableEntityError` |
| 429              | `RateLimitError`           |
| >=500            | `InternalServerError`      |
| N/A              | `APIConnectionError`       |

## IDs de requisição

> Para mais informações sobre depuração de requisições, consulte [ID de requisição](https://platform.claude.com/docs/pt-BR/api/errors#request-id).

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.

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

## Novas tentativas

Certos erros são automaticamente repetidos 2 vezes por padrão, com um breve 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:

```typescript
// 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-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:

```typescript
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, escalonado 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`:

```typescript
// 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-5"
  },
  { timeout: 5 * 1000 }
);
```

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

Observe que as requisições que expiram são [repetidas duas vezes por padrão](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/typescript#retries).

## Requisições longas

<Warning>
  Considere usar a [Messages API](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/typescript#streaming-responses) com streaming para requisições de execução mais longa.
</Warning>

Evite definir um valor grande de `max_tokens` sem usar streaming. Algumas redes podem encerrar conexões ociosas após um certo período de tempo, o que pode fazer com que a requisição falhe ou [expire](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/typescript#timeouts) 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 [substituir](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/typescript#timeouts) 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](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/typescript#timeouts) para uma requisição sem streaming fará com que o cliente encerre a conexão e tente novamente sem receber uma resposta.

Quando suportado pela implementação do `fetch`, o SDK define uma opção de [TCP socket keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html) para reduzir o impacto de timeouts de conexões ociosas em algumas redes. Isso pode ser [substituído](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/typescript#configuring-proxies) 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:

```typescript
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:

```typescript
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 paginar manualmente:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}
```

## Cabeçalhos padrão

O SDK envia automaticamente o cabeçalho `anthropic-version` definido como a versão da API para esta versão principal do SDK (consulte [Versionamento semântico](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/typescript#semantic-versioning)).

Se necessário, você pode substituí-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.

```typescript
const client = new Anthropic();

const message = await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5-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.

```typescript
const client = new Anthropic();

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

### Logging

<Warning>
  Todas as mensagens de log destinam-se apenas à depuração. O formato e o conteúdo das mensagens de log podem mudar entre versões.
</Warning>

#### 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` (substitui a variável de ambiente, se definida)

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

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

* `'debug'` - Mostra mensagens de depuração, informações, avisos e erros
* `'info'` - Mostra mensagens de informação, 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 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](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale) e [@std/log](https://jsr.io/@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.

```typescript
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
});
```

### Tracing do OpenTelemetry

Quando a sua aplicação registra um tracer provider do OpenTelemetry, o SDK emite um span para cada requisição que envia. Para enviar os spans para a sua plataforma de observabilidade, consulte [Configurar o OpenTelemetry com o Claude SDK](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/sdk).

### 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.

```typescript
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.

```typescript
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 um polyfill da global:

```typescript
import fetch from "my-fetch";

globalThis.fetch = fetch;
```

Ou passá-la para o cliente:

```typescript
import fetch from "my-fetch";

const client = new Anthropic({ fetch });
```

### Opções do fetch

Se você quiser definir opções personalizadas do `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 da requisição substituem as opções do cliente.)

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

### Configurando proxies

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

<Tabs>
  <Tab title="Node.js">
    ```typescript
    import * as undici from "undici";

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

  <Tab title="Bun">
    ```typescript
    const client = new Anthropic({
      fetchOptions: {
        proxy: "http://localhost:8888"
      }
    });
    ```
  </Tab>

  <Tab title="Deno">
    ```typescript
    import Anthropic from "npm:@anthropic-ai/sdk";

    const httpClient = Deno.createHttpClient({ proxy: { url: "http://localhost:8888" } });
    const client = new Anthropic({
      fetchOptions: {
        client: httpClient
      }
    });
    ```
  </Tab>
</Tabs>

## Recursos beta

Os recursos beta ficam 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 de Claude na [Visão geral de recursos](https://platform.claude.com/docs/pt-BR/build-with-claude/overview).

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](https://platform.claude.com/docs/pt-BR/api/beta-headers) apropriado ao campo `betas` ao criar uma mensagem.

Por exemplo, para habilitar a [edição de contexto](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing):

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

## Suporte a runtimes

<Accordion title="Uso no navegador">
  Habilitar a opção `dangerouslyAllowBrowser` pode ser perigoso porque expõe suas credenciais secretas da API no código do lado do cliente. Navegadores web são inerentemente menos seguros que ambientes de servidor. Qualquer usuário com acesso ao navegador pode potencialmente inspecionar, extrair e usar indevidamente essas credenciais. Isso pode levar a acesso não autorizado usando suas credenciais e potencialmente comprometer dados ou funcionalidades sensíveis.

  **Quando isso pode não ser perigoso?**

  Em certos cenários, habilitar o suporte a navegadores pode não representar riscos significativos:

  * **Ferramentas internas:** Se a aplicação for usada exclusivamente em um ambiente interno controlado, onde os usuários são confiáveis, o risco de exposição de credenciais pode ser mitigado.
  * **Fins de desenvolvimento ou depuração:** Habilitar esse recurso temporariamente pode ser aceitável, desde que as credenciais tenham vida curta, não sejam usadas também em ambientes de produção ou sejam rotacionadas com frequência.
</Accordion>

## Integrações com plataformas

<Note>
  Para guias detalhados de configuração de plataformas com exemplos de código, consulte:

  * [Amazon Bedrock](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock (Opus 4.6 e anteriores)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws)
  * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/google-managed)
  * [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry)

  Consulte também [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed).
</Note>

O SDK TypeScript oferece suporte às 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.

O SDK TypeScript também oferece suporte a Claude Models on Google Cloud (Anthropic managed) por meio do cliente `AnthropicGoogleCloud`. Este cliente está em beta. Para instalá-lo, execute `npm install @anthropic-ai/google-cloud-sdk`. Passe `workspaceId` para o construtor ou defina a variável de ambiente `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`. Consulte [Resolução de projeto, localização e workspace](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) para saber como o cliente resolve o ID do workspace.

## Versionamento semântico

Cada versão principal deste SDK envia uma versão da API no cabeçalho `anthropic-version` por padrão, e uma nova versão principal acompanha cada nova versão da API. A primeira versão principal que envia `2026-10-21` é a 1.0.0; consulte [Migrando para a versão da API 2026-10-21](https://platform.claude.com/docs/pt-BR/api/migration-2026-10-21#upgrade).

Este pacote geralmente segue as convenções do [SemVer](https://semver.org/spec/v2.0.0.html), embora certas alterações incompatíveis com versões anteriores possam ser lançadas como versões secundárias:

1. Alterações que afetam apenas tipos estáticos, sem quebrar o comportamento em tempo de execução.
2. Alterações em componentes internos da biblioteca que são tecnicamente públicos, mas não destinados ou documentados para uso externo.
3. Alterações 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](https://github.com/anthropics/anthropic-sdk-typescript) para perguntas frequentes, issues e suporte da comunidade.

## Recursos adicionais

* [Repositório do GitHub](https://github.com/anthropics/anthropic-sdk-typescript)
* [Referência da API](https://platform.claude.com/docs/pt-BR/api/overview)
* [Streaming de mensagens](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming)
* [Uso de ferramentas com Claude](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview)