Construir con la API y el Agent SDK

Hasta aquí usaste a Claude por sus productos. Este módulo cruza al otro lado: la API, la puerta por la que tu propio programa le habla al modelo. Sin código (el curso no lo muestra), vas a entender qué lleva una petición, qué cuesta, cómo usa herramientas el modelo, cómo se abarata y cuándo conviene el Agent SDK, para diseñar tu primer agente o encargarlo sabiendo qué pedir.

Funciones y precios están verificados a octubre de 2026; los precios cambian, la lógica de cómo se calculan no.

¿Qué es la API de Claude y cómo consigo una clave?

Una API es la forma en que dos programas se comunican sin una persona en el medio. Tu sistema (un script, un endpoint de tu sitio, un paso de n8n) envía texto a la API de Anthropic y recibe la respuesta del modelo. Sin app de chat ni proyectos: solo el motor y lo que tú construyas alrededor.

La llave es la clave de API. Se crea en la Claude Console (platform.claude.com), en la página de API keys, con nombre y fecha de vencimiento. Empieza por sk-ant- y la Console la muestra completa una sola vez; si la pierdes, creas otra. El uso se paga con créditos prepagados que compras en Settings > Billing; si se acaban, la API deja de responder, y vencen al año.

Se cobra por token, como viste en el módulo 1: los que entran (prompt de sistema, documentos, historial) y los que salen (la respuesta), cada uno con su precio por millón. A octubre de 2026, según la página de precios de Anthropic: Claude Haiku 5.5 cuesta 0,10 dólares por millón de tokens de entrada y 0,50 por millón de salida (en prompts de hasta 100.000 tokens); Sonnet 5.5, 2 y 10; Opus 5.5, 4 y 20; Fable 5.1, 10 y 50.

La fórmula: (tokens de entrada ÷ 1.000.000 × precio de entrada) + (tokens de salida ÷ 1.000.000 × precio de salida). Un mensaje de huésped de 300 tokens, con un prompt de sistema de 2.000 y una respuesta de 400, son 2.300 de entrada y 400 de salida: menos de un milésimo de dólar con Haiku 5.5, poco menos de dos centavos con Opus 5.5. Cada respuesta trae el conteo exacto: no adivinas, mides.

¿Cómo es una petición a la API, explicada en palabras?

La API principal se llama Messages. Una petición es un paquete JSON con cuatro cosas: el modelo (su identificador exacto, por ejemplo claude-haiku-5-5), un {{prompt de sistema|prompt-de-sistema}} opcional (papel, reglas y contexto fijo, como las instrucciones de un proyecto en el módulo 6), los mensajes (la conversación hasta ahora; la API no recuerda nada entre llamadas, así que envías el historial completo cada vez) y max_tokens, el tope de la respuesta.

La respuesta trae lo que tu código lee: el contenido, como lista de bloques; el stop_reason, por qué paró el modelo (end_turn si terminó, max_tokens si se quedó sin espacio, tool_use si quiere una herramienta); y usage, los tokens de entrada y salida que acabas de pagar.

No necesitas escribirla a mano. Anthropic publica SDKs oficiales (Python, TypeScript y otros cinco lenguajes) que lo convierten en pocas líneas, y la Console tiene un Playground (reemplazó al antiguo Workbench) donde armas la petición en el navegador, ves la respuesta con su conteo de tokens y la exportas como código. Es el mejor lugar para tu primera prueba.

¿Cómo usa herramientas el modelo cuando construyes con la API?

El módulo 16 explicó el ciclo agéntico; por API, el uso de herramientas funciona así. Describes tus herramientas en la petición, cada una con nombre, descripción y esquema de parámetros. El modelo nunca ejecuta nada: cuando necesita una, responde con stop_reason tool_use y un bloque que dice cuál y con qué parámetros. Tu código la ejecuta (por ejemplo, consulta el sistema de reservas), devuelve el resultado en un bloque tool_result y vuelve a llamar a la API con todo el historial. Se repite mientras el modelo pida herramientas y termina con end_turn. Ese "mientras" es el bucle que tu programa controla, con límite de vueltas y registro de cada paso.

Hay un segundo tipo: las herramientas de servidor, que Anthropic ejecuta por ti. A octubre de 2026: búsqueda web (10 dólares por cada mil búsquedas, más los tokens), lectura de páginas web y ejecución de código (Python y bash en un contenedor aislado sin internet; gratis junto a la búsqueda web, y sola con 1.550 horas gratis al mes). Los resultados llegan en la misma respuesta. Los SDKs traen además un tool runner (en beta) que corre el bucle por ti cuando no necesitas control fino.

Lo que más pesa no es el código sino la descripción. Las recomendaciones de Anthropic, resumidas:

• Descripciones muy detalladas. Qué hace, cuándo usarla y cuándo no, qué significa cada parámetro, qué no devuelve. Anthropic pide al menos tres o cuatro frases por herramienta y lo llama "por lejos el factor más importante".
• Pocas herramientas, capaces. Agrupa operaciones relacionadas en una con un parámetro de acción, con el nombre del sistema como prefijo (stays_buscar_reserva).
• Respuestas con señal. Solo los campos que el modelo necesita para el siguiente paso, con identificadores legibles.
• Errores que explican. Qué pasó y qué hacer, no un código numérico.

Cuando necesitas un dato con forma fija y no una acción, usa salidas estructuradas: pones un esquema JSON en la petición y la API garantiza que la respuesta lo cumpla. Es la versión por API de lo que hiciste en el módulo 8 con facturas: el formato queda garantizado. El valor, no: la validación en código (subtotal más impuestos igual al total, NIT en tu lista) sigue siendo tuya.

Voy a construir un agente con la API de Claude. Su tarea: [UNA FRASE]. Los sistemas a los que puede acceder: [LISTA, por ejemplo sistema de reservas, hoja de cálculo de proveedores, bandeja de borradores].

Define las herramientas siguiendo las recomendaciones de Anthropic para escribir herramientas para agentes:
- Pocas y capaces: agrupa operaciones relacionadas; usa el nombre del sistema como prefijo.
- Para cada una: nombre (en minúsculas con guiones bajos), descripción de al menos cuatro frases (qué hace, cuándo usarla y cuándo no, qué significa cada parámetro, qué NO devuelve), parámetros con tipo y descripción y cuáles son obligatorios, qué devuelve (solo campos con señal, con identificadores legibles) y los errores posibles con un mensaje que diga qué hacer.
- Marca cuáles son de solo lectura y cuáles tienen efectos; estas últimas deben crear un borrador o una solicitud pendiente, nunca ejecutar la acción final.

Luego escribe tres casos de prueba por herramienta: una entrada válida, una inválida y un caso límite, con el resultado esperado de cada uno.

¿Cómo hago el flujo más barato y más rápido?

Tres palancas, verificadas a octubre de 2026.

1. 1{{Caché de prompts|cache-de-prompts}}. Si cada llamada repite el mismo prefijo (herramientas, prompt de sistema, la biblia de la propiedad), lo marcas con cache_control y la API lo guarda cinco minutos (o una hora, a mayor costo). Escribirlo cuesta 1,25 veces el precio de entrada; leerlo, el 10 por ciento (5 en Opus 5.5 y Sonnet 5.5, 2,5 en Fable 5.1), y responde más rápido. El prefijo debe ser idéntico byte a byte y hay un mínimo de unos 512 tokens. La respuesta dice cuántos tokens leyó de caché; si es cero, algo lo invalida.
2. 2Procesamiento por lotes (Batch API). Para lo que puede esperar (las reseñas del mes, quinientos PDF), envías hasta 100.000 peticiones en un lote y pagas la mitad, en entrada y salida. La mayoría termina en menos de una hora, el máximo es 24 horas y los resultados duran 29 días.
3. 3El modelo pequeño donde alcanza. Anthropic describe el patrón de enrutamiento: un primer paso barato clasifica y decide qué sigue; solo lo difícil llega al modelo grande. La regla son las evaluaciones del módulo 20: cambias el modelo en un paso y mides si la calidad se sostiene.

Ayúdame a estimar el costo mensual de un flujo con la API de Claude. Primero pregúntame, una por una, lo que te falte: cuántos casos al mes, cuántos pasos de IA tiene cada caso, qué modelo usa cada paso, cuántos tokens de entrada tiene un caso típico (prompt de sistema + contexto + mensaje) y cuántos de salida, qué parte del prompt se repite en cada llamada (candidata a caché) y qué parte del volumen puede esperar horas (candidata a lotes).

Con mis respuestas, muestra la aritmética completa:
1. Costo por caso = (tokens de entrada ÷ 1.000.000 × precio de entrada) + (tokens de salida ÷ 1.000.000 × precio de salida), paso por paso.
2. Costo mensual sin optimizar.
3. Costo mensual con caché de prompts sobre la parte repetida (explica el multiplicador de lectura y de escritura que debo verificar).
4. Costo mensual si el volumen que puede esperar va por lotes.
5. Una variante con un modelo menor en el paso más simple, y qué evaluación tendría que pasar para adoptarla.

Usa los precios que yo te dé: [PRECIOS DE LA PÁGINA DE PRECIOS DE ANTHROPIC, CON FECHA]. Si no te los doy, deja los precios como variables y dime que los consulte en platform.claude.com. Termina con el rango (mejor y peor caso) y los dos supuestos que más mueven el resultado.

¿Qué es el Agent SDK y cuándo lo uso en vez de la API?

Construir ese bucle a mano, con permisos, contexto y reintentos, es trabajo. Claude Code ya lo tiene resuelto, y el Agent SDK es exactamente eso: según su documentación, las mismas herramientas, el mismo ciclo y el mismo manejo de contexto que impulsan Claude Code, programables en Python y TypeScript. Instalas un paquete (claude-agent-sdk en Python, @anthropic-ai/claude-agent-sdk en TypeScript) y llamas a una función query con un prompt y opciones: qué herramientas puede usar (leer, editar, correr comandos, buscar en la web), qué modo de permisos, qué prompt de sistema, qué servidores MCP, hooks y subagentes. Se autentica con tu clave de API y se paga por token.

La decisión, en una tabla mental:

• Una llamada a la API (o pocas en cadena): clasificar, extraer, resumir, redactar. La mayoría de las automatizaciones de una pyme viven aquí, y es por donde Anthropic recomienda empezar: la solución más simple, y complejidad solo cuando haga falta.
• La API con tus herramientas (bucle propio o tool runner): cuando el agente consulta tus sistemas y quieres control total de cada vuelta y cada permiso.
• El Agent SDK: cuando el agente necesita leer y editar archivos, correr comandos o buscar en la web dentro de tu propio proceso: un revisor de contratos, un asistente interno con acceso a tu repositorio.
• Claude Code mismo (sesión interactiva o rutina en la nube, módulo 15): cuando hay una persona al teclado o el trabajo cabe en un prompt programado contra un repositorio.
• Claude Managed Agents (en beta a octubre de 2026): Anthropic corre el bucle y el sandbox por ti, con sesiones persistentes y ejecuciones programadas, a cambio de que el estado viva en sus servidores.

¿Cómo diseño mi primer agente para el negocio?

Con un diseño de una página que puedas evaluar antes de pagar una sola llamada. El caso más común en hospitalidad y servicio al cliente: clasificar mensajes entrantes y redactar respuestas que una persona aprueba. Las piezas:

1. 1Entradas. El mensaje del huésped, los datos de su reserva (de tu sistema, no del modelo) y el documento de contexto de la propiedad, la biblia del módulo 2.
2. 2Herramientas. Tres o cuatro: buscar la reserva por código, leer la biblia, crear un borrador en tu bandeja, escalar a una persona con el motivo. Ninguna envía nada.
3. 3Modelos. Haiku 5.5 para clasificar (información, cambio, queja, otro) y Sonnet 5.5 u Opus 5.5 para redactar; se decide con evaluaciones.
4. 4Punto humano. Cada borrador espera aprobación; cambios de reserva, reembolsos y descuentos se escalan. Es el humano en el ciclo del módulo 9 y la mejor defensa contra la inyección de prompt: un supuesto huésped puede esconder instrucciones en su mensaje, pero no puede aprobar su propio borrador.
5. 5Costo. Mides en el Playground los tokens de un caso típico y aplicas la fórmula al volumen del mes, con caché para la biblia y el prompt de sistema.
6. 6{{Criterios de aceptación|criterios-de-aceptacion}}. Cien mensajes reales con la categoría correcta y una respuesta aprobada, como pide el módulo 17, para medir cada versión.

La otra opción igual de buena es la extracción de facturas con validación en código (módulo 8). En los dos casos vale el criterio del módulo 16: si el proceso se describe como pasos fijos, es un flujo de trabajo, no un agente, y cuesta menos.

Actúa como un ingeniero que diseña sistemas con la API de Claude para un negocio pequeño. Mi negocio: [QUÉ HACE, CIUDAD, TAMAÑO]. El proceso que quiero automatizar: [DESCRÍBELO EN 3 A 5 FRASES: qué entra, qué debe salir, quién lo hace hoy y cuánto tarda]. Volumen aproximado: [N CASOS POR MES]. Sistemas donde viven los datos: [LISTA].

Entrega un diseño de una página con estas secciones:
1. Entradas: qué recibe el sistema en cada caso y de dónde sale cada dato (del sistema, del documento de contexto o del mensaje).
2. ¿Flujo fijo o agente? Si los pasos se pueden fijar de antemano, propón un flujo de pasos; usa un agente con bucle solo si justificas por qué.
3. Herramientas: máximo cuatro, con nombre, propósito, parámetros y qué devuelven. Ninguna que envíe, pague o borre sin aprobación.
4. Modelo por paso: cuál y por qué (clasificar, extraer, redactar), y qué evaluación confirmaría que un modelo menor alcanza.
5. Punto de revisión humana: dónde se detiene el sistema, qué ve la persona y qué pasa si rechaza.
6. Método de estimación de costo: qué tokens medir en un caso típico, qué fórmula aplicar y qué palancas (caché, lotes, modelo menor) aplican aquí.
7. Riesgos: datos personales involucrados, inyección de prompt, qué pasa si la API o un sistema no responde.
No inventes precios: dime qué debo consultar en la página de precios de Anthropic.

El siguiente módulo cierra el ciclo: "Evaluar, controlar costos y prevenir fallas", donde el diseño de hoy se mide con evaluaciones, se vigila en producción y se protege de los modos de falla más comunes.