SDK de TypeScript

Esta biblioteca proporciona un acceso conveniente a la Claude API desde TypeScript o JavaScript.

Instalación

npm install @anthropic-ai/sdk

Requisitos

Se admite TypeScript >= 4.9.

Se admiten los siguientes entornos de ejecución:

• Node.js 20 LTS o versiones posteriores (no EOL).
• Deno v1.28.0 o superior.
• Bun 1.0 o posterior.
• Cloudflare Workers.
• Vercel Edge Runtime.
• Jest 28 o superior con el entorno "node" ("jsdom" no se admite por el momento).
• Nitro v2.6 o superior.
• Navegadores web: deshabilitados de forma predeterminada para evitar exponer tus credenciales secretas de la API (consulta las mejores prácticas para claves de API). Habilita la compatibilidad con navegadores estableciendo explícitamente dangerouslyAllowBrowser en true.

Ten en cuenta que React Native no se admite por el momento.

Si te interesan otros entornos de ejecución, abre o vota un issue en el repositorio de 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 conocer las opciones de autenticación, incluida Workload Identity Federation, consulta Autenticación. Si tu clave de API es una clave personal o de cuenta de servicio con acceso a múltiples espacios de trabajo, establece el ID del espacio de trabajo en el encabezado de solicitud anthropic-workspace-id; Seleccionar un espacio de trabajo muestra la opción por solicitud para este SDK.

Tipos de solicitud y respuesta

Esta biblioteca incluye definiciones de TypeScript para todos los parámetros de solicitud y campos de respuesta. Puedes importarlos y usarlos de la siguiente manera:

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);

La documentación de cada método, parámetro de solicitud y campo de respuesta está disponible en los docstrings y aparece al pasar el cursor en la mayoría de los editores modernos.

Conteo de tokens

Puedes ver el uso exacto de una solicitud determinada a través de la propiedad de respuesta usage, por ejemplo:

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

Respuestas en streaming

El SDK ofrece compatibilidad con respuestas en "streaming" (transmisión continua) mediante 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);
}

Si necesitas cancelar un stream, puedes usar break para salir del bucle o llamar a stream.controller.abort().

Helpers de streaming

Esta biblioteca proporciona varias utilidades para el streaming de mensajes, por ejemplo:

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);

El streaming con client.messages.stream(...) expone varios helpers para tu comodidad, incluidos manejadores de eventos y acumulación.

Como alternativa, puedes usar client.messages.create({ ..., stream: true }), que solo devuelve un iterable asíncrono de los eventos del stream y, por lo tanto, usa menos memoria (no construye un objeto de mensaje final por ti).

Helpers de herramientas

Este SDK proporciona helpers para facilitar la creación y ejecución de herramientas en la Messages API. Puedes usar esquemas de Zod o JSON Schemas para describir la entrada de una herramienta. Luego puedes ejecutar esas herramientas usando el método client.beta.messages.toolRunner(). Este método se encarga de pasar las entradas generadas por el modelo elegido a la herramienta correcta y de devolver el resultado al modelo.

Para más detalles sobre el "tool use" (uso de herramientas), consulta Uso de herramientas con 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);

Errores de herramientas

Para informar al modelo de un error de una herramienta, lanza un ToolError desde la función run. A diferencia de un Error simple, ToolError acepta bloques de contenido, lo que te permite incluir imágenes u otro contenido estructurado en la respuesta de error:

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) {
      // Incluye la captura de pantalla del error para que el modelo pueda ver qué salió mal
      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" }
    };
  }
});

Si se lanza un Error simple, el mensaje se convertirá en un bloque de contenido de texto.

Uso de herramientas

Este SDK ofrece compatibilidad con el uso de herramientas, también conocido como llamada de funciones (function calling). Para más detalles, consulta Uso de herramientas con Claude.

Helpers de MCP

Este SDK proporciona helpers para la integración con servidores de Model Context Protocol (MCP). Estos helpers convierten los tipos de MCP en tipos de la Claude API, lo que reduce el código repetitivo al trabajar con herramientas, prompts y recursos de 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();

// Conéctate a un 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);

// Usa prompts de 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);

// Usa herramientas de MCP con 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);

// Usa recursos de MCP como contenido
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" }
      ]
    }
  ]
});

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

Manejo de errores de MCP

Las funciones de conversión lanzan UnsupportedMCPValueError si un valor de MCP no es compatible con la Claude API (por ejemplo, tipo de contenido no admitido, tipo MIME no admitido, enlace de recurso que no es http/https).

Lotes de mensajes

Este SDK ofrece compatibilidad con el procesamiento por lotes bajo el espacio de nombres client.messages.batches.

Crear un lote

Message Batches recibe un arreglo de solicitudes, donde cada objeto tiene un identificador custom_id y exactamente los mismos params de solicitud que la Messages API estándar:

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" }]
      }
    }
  ]
});

Obtener los resultados de un lote

Una vez que se ha procesado un Message Batch, lo cual se indica con .processing_status === 'ended', puedes acceder a los resultados con .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);
  }
}

Carga de archivos

Los parámetros de solicitud que corresponden a cargas de archivos se pueden pasar de muchas formas diferentes:

• File (o un objeto con la misma estructura)
• una Response de fetch (o un objeto con la misma estructura)
• un fs.ReadStream
• el valor de retorno del helper toFile

Establece el content-type explícitamente, ya que la API de archivos no lo inferirá por ti:

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

const client = new Anthropic();

// Si tienes acceso a `fs` de Node, usa `fs.createReadStream()`:
await client.files.upload({
  file: await toFile(fs.createReadStream("/path/to/file"), undefined, {
    type: "application/json"
  })
});

// O si tienes la API web `File`, puedes pasar una instancia de `File`:
await client.files.upload({
  file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// También puedes pasar un `Response` de `fetch`:
await client.files.upload({
  file: await fetch("https://somesite/file")
});

// O un `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" })
});

Manejo de errores

Cuando la biblioteca no puede conectarse a la API, o si la API devuelve un código de estado no exitoso (es decir, una respuesta 4xx o 5xx), se lanza una subclase de APIError:

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

Los códigos de error son los siguientes:

IDs de solicitud

Para más información sobre la depuración de solicitudes, consulta ID de solicitud.

Todas las respuestas de objeto en el SDK proporcionan una propiedad _request_id que se agrega a partir del encabezado de respuesta request-id, para que puedas registrar rápidamente las solicitudes fallidas e informarlas a 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

Reintentos

Ciertos errores se reintentan automáticamente 2 veces de forma predeterminada, con un breve retroceso exponencial. Los errores de conexión (por ejemplo, debido a un problema de conectividad de red), 408 Request Timeout, 409 Conflict, 429 Rate Limit y los errores internos >=500 se reintentan de forma predeterminada.

Puedes usar la opción maxRetries para configurar o deshabilitar esto:

// Configura el valor predeterminado para todas las solicitudes:
const client = new Anthropic({
  maxRetries: 0 // default is 2
});

// O bien, configúralo por solicitud:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-5"
  },
  { maxRetries: 5 }
);

Tiempos de espera

De forma predeterminada, las solicitudes agotan el tiempo de espera después de 10 minutos. Sin embargo, si has especificado un valor grande de max_tokens y no estás usando streaming, el tiempo de espera predeterminado se calculará dinámicamente usando la fórmula:

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

lo que dará como resultado un tiempo de espera de hasta 60 minutos, escalado según el parámetro max_tokens, a menos que se sobrescriba a nivel de solicitud o de cliente.

Puedes configurar esto con la opción timeout:

// Configura el valor predeterminado para todas las solicitudes:
const client = new Anthropic({
  timeout: 20 * 1000 // 20 seconds (default is 10 minutes)
});

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

Al agotarse el tiempo de espera, se lanza un APIConnectionTimeoutError.

Ten en cuenta que las solicitudes que agotan el tiempo de espera se reintentan dos veces de forma predeterminada.

Solicitudes largas

Evita establecer un valor grande de max_tokens sin usar streaming. Algunas redes pueden descartar conexiones inactivas después de cierto período de tiempo, lo que puede provocar que la solicitud falle o agote el tiempo de espera sin recibir una respuesta de Anthropic.

Este SDK también lanza un error si se espera que una solicitud sin streaming dure más de aproximadamente 10 minutos. Pasar stream: true o sobrescribir la opción timeout a nivel de cliente o de solicitud deshabilita este error.

Una latencia de solicitud esperada mayor que el tiempo de espera para una solicitud sin streaming hará que el cliente termine la conexión y reintente sin recibir una respuesta.

Cuando la implementación de fetch lo admite, el SDK establece una opción de keep-alive de socket TCP para reducir el impacto de los tiempos de espera por conexiones inactivas en algunas redes. Esto se puede sobrescribir configurando un proxy personalizado.

Paginación automática

Los métodos de listado en la Claude API están paginados. Puedes usar la sintaxis for await ... of para iterar sobre los elementos de todas las páginas:

async function fetchAllMessageBatches() {
  const allMessageBatches = [];
  // Obtiene automáticamente más páginas según sea necesario.
  for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
    allMessageBatches.push(messageBatch);
  }
  return allMessageBatches;
}

Como alternativa, puedes solicitar una sola página a la vez:

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

// Se proporcionan métodos de conveniencia para paginar manualmente:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

Encabezados predeterminados

El SDK envía automáticamente el encabezado anthropic-version establecido en 2023-06-01.

Si lo necesitas, puedes sobrescribirlo estableciendo encabezados predeterminados por solicitud.

Ten en cuenta que hacerlo puede dar lugar a tipos incorrectos y otros comportamientos inesperados o indefinidos en el 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 avanzado

Acceder a los datos sin procesar de Response (por ejemplo, encabezados)

Se puede acceder a la Response "sin procesar" devuelta por fetch() a través del método .asResponse() del tipo APIPromise que devuelven todos los métodos. Este método retorna tan pronto como se reciben los encabezados de una respuesta exitosa y no consume el cuerpo de la respuesta, por lo que tienes libertad para escribir lógica personalizada de análisis o streaming.

También puedes usar el método .withResponse() para obtener la Response sin procesar junto con los datos analizados. A diferencia de .asResponse(), este método consume el cuerpo y retorna una vez que se ha analizado.

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);

Registro de logs

Niveles de log

Puedes configurar el nivel de log de dos maneras:

1. A través de la variable de entorno ANTHROPIC_LOG
2. Usando la opción de cliente logLevel (sobrescribe la variable de entorno si está establecida)

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

Niveles de log disponibles, del más al menos detallado:

• 'debug' - Muestra mensajes de depuración, información, advertencias y errores
• 'info' - Muestra mensajes de información, advertencias y errores
• 'warn' - Muestra advertencias y errores (predeterminado)
• 'error' - Muestra solo errores
• 'off' - Deshabilita todos los logs

En el nivel 'debug', se registran todas las solicitudes y respuestas HTTP, incluidos los encabezados y los cuerpos. Algunos encabezados relacionados con la autenticación se ocultan, pero los datos sensibles en los cuerpos de las solicitudes y respuestas aún pueden ser visibles.

Logger personalizado

De forma predeterminada, esta biblioteca registra los logs en globalThis.console. También puedes proporcionar un logger personalizado. Se admite la mayoría de las bibliotecas de logging, incluidas pino, winston, bunyan, consola, signale y @std/log. Si tu logger no funciona, abre un issue.

Al proporcionar un logger personalizado, la opción logLevel sigue controlando qué mensajes se emiten; los mensajes por debajo del nivel configurado no se enviarán a tu 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
});

Realizar solicitudes personalizadas/no documentadas

Esta biblioteca está tipada para un acceso conveniente a la API documentada. Si necesitas acceder a endpoints, parámetros o propiedades de respuesta no documentados, aún puedes usar la biblioteca.

Endpoints no documentados

Para realizar solicitudes a endpoints no documentados, puedes usar client.get, client.post y otros verbos HTTP. Las opciones del cliente, como los reintentos, se respetan al realizar estas solicitudes.

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

Parámetros de solicitud no documentados

Para realizar solicitudes usando parámetros no documentados, puedes usar // @ts-expect-error en el parámetro no documentado. Esta biblioteca no valida en tiempo de ejecución que la solicitud coincida con el tipo, por lo que cualquier valor adicional que envíes se enviará tal cual.

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

Para las solicitudes con el verbo GET, cualquier parámetro adicional irá en la query; todas las demás solicitudes enviarán el parámetro adicional en el cuerpo.

Si quieres enviar explícitamente un argumento adicional, puedes hacerlo con las opciones de solicitud query, body y headers.

Propiedades de respuesta no documentadas

Para acceder a propiedades de respuesta no documentadas, puedes acceder al objeto de respuesta con // @ts-expect-error en el objeto de respuesta, o convertir el objeto de respuesta al tipo requerido. Al igual que con los parámetros de solicitud, el SDK no valida ni elimina las propiedades adicionales de la respuesta de la API.

Personalizar el cliente fetch

De forma predeterminada, esta biblioteca espera que esté definida una función fetch global.

Si quieres usar una función fetch diferente, puedes aplicar un polyfill a la global:

import fetch from "my-fetch";

globalThis.fetch = fetch;

O pasarla al cliente:

import fetch from "my-fetch";

const client = new Anthropic({ fetch });

Opciones de fetch

Si quieres establecer opciones personalizadas de fetch sin sobrescribir la función fetch, puedes proporcionar un objeto fetchOptions al crear el cliente o al realizar una solicitud. (Las opciones específicas de la solicitud sobrescriben las opciones del cliente).

const client = new Anthropic({
  fetchOptions: {
    // opciones de `RequestInit`
  }
});

Configurar proxies

Para modificar el comportamiento del proxy, puedes proporcionar fetchOptions personalizadas que agreguen opciones de proxy específicas del entorno de ejecución a las solicitudes:

import * as undici from "undici";

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

Funcionalidades beta

Las funcionalidades beta están disponibles antes del lanzamiento general para obtener retroalimentación temprana y probar nuevas funcionalidades. Puedes verificar la disponibilidad de todas las capacidades y herramientas de Claude en la descripción general de construir con Claude.

Puedes acceder a la mayoría de las funcionalidades beta de la API a través de la propiedad beta del cliente. Para habilitar una funcionalidad beta en particular, debes agregar el encabezado beta correspondiente al campo betas al crear un mensaje.

Por ejemplo, para habilitar la edición 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"]
});

Compatibilidad con entornos de ejecución

Integraciones con plataformas

El SDK de TypeScript es compatible con las siguientes plataformas:

• Agent Platform: npm install @anthropic-ai/vertex-sdk: Proporciona el cliente AnthropicVertex
• Bedrock: npm install @anthropic-ai/bedrock-sdk: Proporciona el cliente AnthropicBedrockMantle, y AnthropicBedrock para la ruta bedrock-runtime
• Claude Platform en AWS: npm install @anthropic-ai/aws-sdk: Proporciona el cliente AnthropicAws. Pasa workspaceId al constructor o establece la variable de entorno ANTHROPIC_AWS_WORKSPACE_ID. Disponible en beta.
• Foundry: npm install @anthropic-ai/foundry-sdk: Proporciona el cliente AnthropicFoundry

Usa AnthropicBedrockMantle para proyectos nuevos; AnthropicBedrock se mantiene para aplicaciones existentes que usan la API InvokeModel de Bedrock.

Versionado semántico

Este paquete generalmente sigue las convenciones de SemVer, aunque ciertos cambios incompatibles con versiones anteriores pueden publicarse como versiones menores:

1. Cambios que solo afectan a los tipos estáticos, sin romper el comportamiento en tiempo de ejecución.
2. Cambios en los componentes internos de la biblioteca que son técnicamente públicos pero no están destinados ni documentados para uso externo.
3. Cambios que no se espera que afecten a la gran mayoría de los usuarios en la práctica.

La compatibilidad con versiones anteriores se toma en serio para garantizar que puedas contar con una experiencia de actualización fluida.

Preguntas frecuentes

Consulta el repositorio de GitHub para ver preguntas frecuentes, issues y soporte de la comunidad.

Recursos adicionales

• Repositorio de GitHub
• Referencia de la API
• Streaming de mensajes
• Uso de herramientas con Claude