SDK de TypeScript

Esta biblioteca proporciona acceso conveniente a la API REST de Anthropic 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 es compatible en este momento).
• Nitro v2.6 o superior.
• Navegadores web: deshabilitado 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 es compatible en este momento.

Si estás interesado en otros entornos de ejecución, abre o vota por un issue en 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 conocer las opciones de autenticación, incluida Workload Identity Federation, consulta Autenticación.

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-4-8"
};
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 aparecerá 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 proporciona compatibilidad con respuestas en streaming mediante "Server Sent Events" (eventos enviados por el servidor), o 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);
}

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

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

Alternativamente, 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 que facilitan 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 encargará de pasar las entradas generadas por el modelo elegido a la herramienta correcta y de devolver el resultado al modelo.

Para obtener más detalles sobre el 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-4-8",
  max_tokens: 1000,
  messages: [{ role: "user", content: "What is the weather in San Francisco?" }],
  tools: [weatherTool]
});

console.log(finalMessage.content);

Errores de herramientas

Para reportar un error de una herramienta al modelo, 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 proporciona compatibilidad con el uso de herramientas, también conocido como "function calling" (llamadas a funciones). Para obtener 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 tipos de MCP a tipos de la API de Claude, reduciendo 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();

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

// Usar prompts de 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 herramientas de MCP con 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 de MCP como contenido
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" }
      ]
    }
  ]
});

// Subir recursos de MCP como archivos
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.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 API de Claude (por ejemplo, tipo de contenido no compatible, tipo MIME no compatible, enlace de recurso que no es http/https).

Lotes de mensajes

Este SDK proporciona compatibilidad con la Message Batches API 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-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" }]
      }
    }
  ]
});

Obtener resultados de un lote

Una vez que un Message Batch ha sido procesado, lo cual se indica mediante .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)
• un 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 "fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";

const client = new Anthropic();

// Si tienes acceso a `fs` de Node, usa `fs.createReadStream()`:
await client.beta.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.beta.files.upload({
  file: new File(["my bytes"], "file.txt", { type: "text/plain" })
});
// También puedes pasar un `Response` de `fetch`:
await client.beta.files.upload({
  file: await fetch("https://somesite/file")
});

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

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

Los códigos de error son los siguientes:

IDs de solicitud

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

Todas las respuestas de objetos en el SDK proporcionan una propiedad _request_id que se agrega desde el encabezado de respuesta request-id para que puedas registrar rápidamente las solicitudes fallidas y reportarlas a 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

Reintentos

Ciertos errores se reintentarán 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 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, configura por solicitud:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-8"
  },
  { 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 resultará en un tiempo de espera de hasta 60 minutos, escalado por el parámetro max_tokens, a menos que se anule a nivel de solicitud o de cliente.

Puedes configurar esto con una opción timeout:

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

// Anula por solicitud:
await client.messages.create(
  {
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    model: "claude-opus-4-8"
  },
  { 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 reintentarán dos veces de forma predeterminada.

Solicitudes largas

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

Este SDK también lanzará un error si se espera que una solicitud sin streaming dure aproximadamente más de 10 minutos. Pasar stream: true o anular 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 TCP socket keep-alive para reducir el impacto de los tiempos de espera de conexiones inactivas en algunas redes. Esto se puede anular configurando un proxy personalizado.

Paginación automática

Los métodos de lista en la API de Claude están paginados. Puedes usar la sintaxis for await ... of para iterar a través de los elementos en 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;
}

Alternativamente, 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 anularlo estableciendo encabezados predeterminados por solicitud.

Ten en cuenta que hacerlo puede resultar en tipos incorrectos y otro comportamiento inesperado o indefinido 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-4-8"
  },
  { headers: { "anthropic-version": "My-Custom-Value" } }
);

Uso avanzado

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

Se puede acceder al Response "sin procesar" devuelto por fetch() a través del método .asResponse() en el 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 eres libre de escribir lógica personalizada de análisis o streaming.

También puedes usar el método .withResponse() para obtener el 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-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);

Registro de logs

Niveles de log

El nivel de log se puede configurar de dos maneras:

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

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

Niveles de log disponibles, de más a 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 todo el registro de 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 redactan, pero los datos sensibles en los cuerpos de solicitud y respuesta aún pueden ser visibles.

Logger personalizado

De forma predeterminada, esta biblioteca registra en globalThis.console. También puedes proporcionar un logger personalizado. La mayoría de las bibliotecas de logging son compatibles, 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, la biblioteca aún se puede usar.

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 respetarán 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 solicitudes con el verbo GET, cualquier parámetro adicional estará en la query; todas las demás solicitudes enviarán el parámetro adicional en el cuerpo.

Si deseas 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 los parámetros de solicitud, el SDK no valida ni elimina 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 deseas usar una función fetch diferente, puedes hacer un polyfill de 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 deseas establecer opciones personalizadas de fetch sin anular 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 anulan 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:

Funciones beta

Las funciones 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 funciones beta de la API a través de la propiedad beta del cliente. Para habilitar una función beta en particular, debes agregar el encabezado beta apropiado al campo betas al crear un mensaje.

Por ejemplo, para usar la 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"]
});

Compatibilidad con entornos de ejecución

Integraciones de plataforma

El SDK de TypeScript es compatible con las siguientes plataformas:

• Bedrock: npm install @anthropic-ai/bedrock-sdk: Proporciona el cliente AnthropicBedrockMantle, y AnthropicBedrock para la ruta bedrock-runtime
• Vertex AI: npm install @anthropic-ai/vertex-sdk: Proporciona el cliente AnthropicVertex
• Foundry: npm install @anthropic-ai/foundry-sdk: Proporciona el cliente AnthropicFoundry
• 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.

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 confiar en una experiencia de actualización fluida.

Preguntas frecuentes

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

Recursos adicionales

• Repositorio de GitHub
• Referencia de la API
• Mensajes en streaming
• Uso de herramientas con Claude