Referencia Técnica

Messages API POST /v1/messages

Los modos de interacción

Un desarrollador llega a Claude por una API REST, normalmente a través de un SDK. La elección del modo se decide con dos preguntas: ¿hay alguien esperando? y ¿es tiempo real o volumen offline?

La ventana de contexto y sus dos formas de romperse

Es un presupuesto fijo de tokens que sostiene la petición entera de golpe: system, historial, tools, documentos y la generación. Falla de dos maneras distintas, y el examen puede pedir distinguirlas:

Valores de stop_reason

Tool use

Definición de una tool

{
  "name": "buscar_pedido",          // ^[a-zA-Z0-9_-]{1,64}$
  "description": "...",             // 3-4 frases mínimo, incluir cuándo NO usarla
  "input_schema": { ... },          // JSON Schema
  "input_examples": [ ... ]         // opcional, útil en inputs anidados
}

Valores de tool_choice

Con any o tool, la API hace prefill del turno: no habrá texto antes del tool_use. El paralelismo viene activado; se apaga con disable_parallel_tool_use: true dentro de tool_choice.

Devolver el resultado

{
  "role": "user",                   // no existe rol "tool"
  "content": [
    { "type": "tool_result",
      "tool_use_id": "toolu_...",   // obligatorio
      "content": "...",             // opcional
      "is_error": true },           // opcional: fallo legible para el modelo
    { "type": "text", "text": "..." } // el texto va DESPUÉS
  ]
}

Streaming stream: true

message_start
  content_block_start   // por cada bloque, con su index
  content_block_delta   // N veces
  content_block_stop    // AQUÍ el bloque está cerrado
message_delta           // usage acumulativo
message_stop            // AQUÍ el turno se confirma

Message Batches

Prompt caching cache_control

{ "type": "text", "text": "...",
  "cache_control": { "type": "ephemeral", "ttl": "1h" } }
// "ephemeral" es el único tipo. ttl opcional: por defecto 5 min

Razonamiento y effort

Salida estructurada

Dos mecanismos: JSON outputs (esquema en output_config.format, restringe la respuesta final) y strict tool use (strict: true en una tool, valida los argumentos). Ambos por decodificación restringida.

Errores y estrategia de reintento

La clasificación de fallos

• Primera pregunta ante cualquier fallo: ¿esperar y reintentar podría resolverlo?
• Si sí → backoff exponencial con tope y presupuesto de reintentos. Nunca un bucle inmediato, que solo agrava el problema.
• Si no → fallback con nombre. Sin él, la excepción no gestionada se convierte en el comportamiento por defecto, y una respuesta mala tumba el flujo entero.
• Fallo de tool → vuelve al modelo con la bandera de error puesta, nunca escondido tras un resultado vacío que el modelo confundiría con datos.

Los SDK oficiales ya reintentan con backoff exponencial, 2 reintentos por defecto, respetando retry-after.

Evals: método de grading según la salida

Orden de preferencia oficial: código → LLM → humano. Sobre el humano, la doc dice literalmente «evítalo si puedes». Y el principio de diseño: más casos con señal algo peor y grading automático supera a pocos casos calificados a mano.

Niveles de test y qué caza cada uno

El mismo instinto rige la recuperación de información: una sola búsqueda para consultas de un solo dato, búsqueda a lo largo de varias iteraciones cuando la pregunta es genuinamente multi-paso.

Hooks

Forma de retorno de PreToolUse

{ "permissionDecision": "deny",        // allow | deny | ask | defer
  "permissionDecisionReason": "...",
  "updatedInput": { ... } }            // opcional

• Exit 2 = error bloqueante, no anulable ni con un allow.
• Silencio no es aprobación: un hook puede denegar, pero callarse deja seguir el flujo normal de permisos.
• Los hooks corren en tu proceso, fuera de la ventana de contexto: no consumen tokens salvo lo que devuelvan.

Agent SDK

AgentDefinition de un subagente

{ "description": "...",   // obligatorio
  "prompt": "...",        // obligatorio - lo ÚNICO que cruza del padre
  "tools": [...],         // si se omite, hereda todas
  "model": "inherit",     // o un modelo concreto
  "skills": [...] }       // los subagentes NO precargan skills

MCP

Nomenclatura en Claude Code: tools mcp__servidor__tool · prompts /mcp__servidor__prompt · resources @servidor:proto://ruta.

Límites y contadores