Conceptos básicos del SDK de TypeScript/JavaScript

11 ejemplos para empezar con el SDK de TypeScript/JavaScript, 7 básicos y 4 intermedios.

Prerrequisitos / Instalación rápida

• Node.js 18+ (o un entorno de ejecución de borde como Vercel Edge, Cloudflare Workers o Deno Deploy, ya que el SDK se basa en fetch).
• Instala el paquete: npm install @anthropic-ai/sdk.
• Una clave de API de la Consola de Claude, configurada como la variable de entorno ANTHROPIC_API_KEY.
• Se recomienda TypeScript 5+ para obtener los tipos integrados del SDK sin configuración adicional.

Ejemplos básicos

1. Instalar el paquete

Añade el SDK oficial a tu proyecto con tu gestor de paquetes preferido.

npm install @anthropic-ai/sdk

• El SDK incluye sus propios tipos de TypeScript, por lo que no se necesita un paquete @types separado.
• Se basa en fetch internamente, por lo que se ejecuta sin modificaciones en entornos Node.js y de borde.
• Funciona con npm, pnpm, yarn o bun, ya que se publica como un paquete npm estándar.

2. Configurar la clave de API mediante variable de entorno

Almacena tu clave de API fuera del código fuente y deja que el cliente la recoja automáticamente.

# .env.local (nunca incluyas este archivo en el control de versiones)
ANTHROPIC_API_KEY=sk-ant-...

• El SDK lee process.env.ANTHROPIC_API_KEY por defecto, por lo que rara vez necesitarás pasar una clave explícitamente en el código.
• Mantener la clave en una variable de entorno evita que se filtre en el control de versiones o en los paquetes del lado del cliente.
• En Next.js, solo haz referencia a esta variable desde código del lado del servidor (manejadores de rutas, acciones de servidor), nunca en componentes del lado del cliente.
• Utiliza un gestor de secretos o la configuración de variables de entorno de tu proveedor de alojamiento en producción en lugar de un archivo .env incluido.

3. Instanciar el cliente

Crea una instancia del cliente Anthropic una vez y reutilízala en las solicitudes.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
// Lee ANTHROPIC_API_KEY de process.env automáticamente

• new Anthropic() sin argumentos recoge ANTHROPIC_API_KEY del entorno.
• Puedes anular la clave explícitamente con new Anthropic({ apiKey: "..." }) si la estás cargando desde una fuente de secretos personalizada.
• Crea el cliente una vez en el ámbito del módulo e impórtalo donde sea necesario, en lugar de construir una nueva instancia por solicitud.
• El mismo cliente funciona en entornos Node.js y de borde sin ninguna configuración condicional.

Relacionado: El modelo mental del SDK de TypeScript de Anthropic - cómo el cliente y su transporte basado en fetch encajan entre sí.

4. Enviar un mensaje básico

Llama a client.messages.create() para obtener una respuesta única y no transmitida desde Claude.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Explica qué es una clausura en una sola frase." }],
});
 
console.log(message.content);

• model, max_tokens y messages son los campos requeridos para una llamada a messages.create().
• claude-sonnet-5 es el modelo por defecto en la línea actual de Claude y un buen punto de partida para la mayoría de las tareas.
• La llamada devuelve una promesa, por lo que debe ser esperada (o manejada con .then()).
• message.content es un array de bloques de contenido, no una cadena de texto simple, ya que una respuesta puede mezclar texto, llamadas a herramientas y otros tipos de bloques.

Relacionado: Referencia de tipos del SDK de TypeScript para bloques de contenido - qué hay realmente dentro de ese array de contenido.

5. Leer la respuesta tipada

Acota los bloques de contenido de la respuesta utilizando los tipos de unión discriminados del SDK.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Saluda en tres idiomas." }],
});
 
for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

• Cada bloque de contenido tiene un discriminante type ("text", "tool_use", "thinking", etc.), que TypeScript utiliza para acotar el tipo.
• Comprobar block.type === "text" antes de leer block.text te proporciona seguridad en tiempo de compilación en lugar de una suposición tipada como any.
• El tipo de respuesta también incluye usage, stop_reason y role, todos ellos completamente tipados.
• Este patrón se escala directamente a las respuestas de uso de herramientas, donde comprobarías block.type === "tool_use" en su lugar.

6. Mantener una conversación de varios turnos

Construye el array messages a lo largo de los turnos para dar a Claude el historial de la conversación.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const history: Anthropic.MessageParam[] = [
  { role: "user", content: "¿Cuál es la capital de Francia?" },
  { role: "assistant", content: "La capital de Francia es París." },
  { role: "user", content: "¿Cuál es su población?" },
];
 
const reply = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 512,
  messages: history,
});

• Anthropic.MessageParam es el tipo exportado para una entrada de mensaje individual, útil para tipar arrays que construyes con el tiempo.
• Claude no tiene memoria de los turnos anteriores en el servidor; la conversación completa debe reenviarse como messages en cada llamada.
• Los roles se alternan entre "user" y "assistant", y el array generalmente debe comenzar con un mensaje de "user".
• Añade el texto de cada nueva respuesta a history antes de la siguiente llamada para mantener la conversación creciendo correctamente.

7. Establecer un prompt del sistema y un límite de tokens

Dirige el comportamiento de Claude con un prompt system, separado de la conversación en sí.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 256,
  system: "Eres un asistente conciso. Responde en una sola frase.",
  messages: [{ role: "user", content: "¿Por qué el cielo es azul?" }],
});

• system es un parámetro de nivel superior, no un mensaje con el rol "system", y se aplica a toda la solicitud.
• max_tokens limita la longitud de la respuesta de Claude y se cuenta contra tu uso, así que establécelo en lo que la tarea realmente necesita.
• Reducir max_tokens de forma demasiado agresiva puede cortar una respuesta a mitad de pensamiento; comprueba stop_reason en la respuesta si las respuestas parecen truncadas.
• Cambia claude-sonnet-5 por claude-haiku-4-5 en rutas sensibles a la latencia o claude-opus-4-8 para las tareas de razonamiento más difíciles.

Ejemplos intermedios

8. Transmitir una respuesta con iteradores asíncronos

Consume tokens a medida que llegan en lugar de esperar la respuesta completa.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const stream = client.messages.stream({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Escribe un haiku sobre bases de datos." }],
});
 
for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

• client.messages.stream() devuelve un iterable asíncrono, por lo que for await consume eventos sin necesidad de configurar manualmente listeners de eventos.
• Cada evento está tipado y se discrimina por event.type, reflejando el patrón utilizado para los bloques de contenido.
• El stream también expone métodos de ayuda como .finalMessage() si deseas el resultado ensamblado después de que el bucle termine.
• Prefiere la transmisión para cualquier cosa que se muestre en vivo en una interfaz de usuario; utiliza messages.create() cuando solo necesites el texto final.

Relacionado: Iteradores asíncronos para la transmisión en el SDK de TypeScript - una mirada más profunda al consumo de eventos de stream.

9. Capturar errores tipados

Maneja fallos de la API con las clases de error específicas del SDK en lugar de una captura genérica.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
try {
  await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hola" }],
  });
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    console.warn("Límite de tasa alcanzado, retrocede y reintenta.");
  } else if (error instanceof Anthropic.APIConnectionError) {
    console.error("Problema de red al alcanzar la API.");
  } else {
    throw error;
  }
}

• Las clases de error como RateLimitError, BadRequestError y APIConnectionError te permiten ramificar con instanceof con un estrechamiento de tipo completo.
• Cada error contiene un código de status y detalles de la respuesta, útiles para registrar o mostrar un mensaje específico a los usuarios.
• Volver a lanzar errores desconocidos (la rama else) evita tragar silenciosamente errores que no anticipaste.
• Este patrón merece la pena envolverlo en una utilidad compartida una vez que tengas más de uno o dos sitios de llamada.

Relacionado: Referencia de clases de error del SDK de TypeScript - la lista completa de clases de error y cuándo se produce cada una.

10. Configurar reintentos, tiempos de espera y cancelación

Ajusta la configuración de resiliencia y cancela las solicitudes en curso con AbortController.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic({
  maxRetries: 3,
  timeout: 20_000,
});
 
const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);
 
const message = await client.messages.create(
  {
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Resume esto en una línea." }],
  },
  { signal: controller.signal }
);

• maxRetries y timeout son valores predeterminados a nivel de cliente; ambos también se pueden anular por solicitud.
• Pasar la signal de un AbortController como una opción de solicitud te permite cancelar una llamada desde la interacción del usuario (como un botón "Detener generación").
• Esto funciona de la misma manera en entornos Node y del navegador, ya que ambos implementan la API estándar AbortController.
• Los reintentos solo se activan para fallos que se pueden reintentar (como errores de red transitorios o límites de tasa), no para errores de validación.

Relacionado: Patrones de reintento, tiempo de espera y AbortController en el SDK de TypeScript - ajuste de retroceso y cancelación con más detalle.

11. Ejecutar el mismo cliente en un entorno de borde

Utiliza el mismo código de cliente en una función de borde de Vercel, un Cloudflare Worker o un servidor Node.

export const runtime = "edge";
 
import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
export async function POST(request: Request) {
  const { prompt } = await request.json();
 
  const message = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 512,
    messages: [{ role: "user", content: prompt }],
  });
 
  return Response.json(message);
}

• Dado que el SDK se basa en fetch, este manejador de rutas no necesita APIs específicas de Node y se ejecuta sin cambios bajo export const runtime = "edge".
• La misma llamada new Anthropic() funciona tanto si el código se ejecuta en Node.js, Vercel Edge, Cloudflare Workers o Deno Deploy.
• Los entornos de borde suelen tener límites más estrictos de memoria y tiempo de ejecución, así que mantén max_tokens y cualquier bucle de transmisión conscientes de ello.
• Las variables de entorno como ANTHROPIC_API_KEY aún deben configurarse específicamente para el entorno de borde, ya que es un entorno de ejecución diferente al de tu implementación de Node.

Relacionado: Ejecución del SDK de Anthropic en entornos de borde - configuración y problemas específicos del borde | Definiciones de herramientas fuertemente tipadas con Zod en TypeScript - tipado de llamadas a herramientas una vez que vas más allá de los mensajes de texto plano.

Versiones de la pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de TypeScript @anthropic-ai/sdk (última versión). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.