Anatomía de una solicitud de API

Cada llamada a Claude es una solicitud a la Messages API. Como arquitecto, no necesita memorizar la sintaxis; debe razonar sobre seis campos que determinan toda la interacción: model, max_tokens, system, messages, tools y tool_choice.

Si configura correctamente estos campos, todo lo demás —agentes, bucles de herramientas y salidas estructuradas— encaja. En esta lección se explica cada campo y la decisión que representa.

El campo model selecciona qué Claude realizará el trabajo. Es una sola cadena y la elección implica un equilibrio arquitectónico real entre capacidad, latencia y coste.

• Opus: el más capaz, ideal para agentes con horizontes prolongados y razonamientos complejos.
• Sonnet: equilibrio sólido entre velocidad e inteligencia.
• Haiku: el más rápido y económico para tareas sencillas y de gran volumen.

Puede cambiar el modelo en cada solicitud, de modo que puede dirigir las tareas sencillas a un modelo más económico y las difíciles a uno más potente.

max_tokens es un límite estricto para la cantidad de tokens que Claude puede generar en esta respuesta. El modelo no recibe este número; es un límite impuesto, no una sugerencia.

Si la generación alcanza el límite, la respuesta se corta y stop_reason devuelve "max_tokens". Esto significa que la respuesta está truncada, no completa. Establezca un valor suficientemente alto para terminar el trabajo; en salidas muy largas, use streaming para no alcanzar los tiempos de espera de la solicitud.

El prompt system define el rol, el tono y las reglas permanentes de Claude: las instrucciones que se aplican a toda la conversación, no solo a un turno del usuario.

Coloque aquí el comportamiento duradero: "Usted es un agente de soporte. Verifique la identidad del cliente antes de realizar cualquier acción en su cuenta." Manténgalo estable entre solicitudes; un prompt del sistema fijo también se almacena bien en caché, lo que reduce el coste y la latencia de las llamadas repetidas.

Este es el campo que los arquitectos configuran mal con mayor frecuencia. La Messages API es sin estado: el modelo NO conserva memoria entre solicitudes. En cada turno debe volver a enviar el historial completo de la conversación: todos los turnos anteriores del usuario y del asistente, además de los resultados de las herramientas.

Si solo envía el último mensaje del usuario, Claude sufrirá amnesia. El estado de la conversación vive en su aplicación; debe reproducirlo en cada llamada. Los mensajes alternan los roles y el primero debe ser user.

El campo tools es una lista de acciones que Claude puede invocar; cada una incluye un name, un input_schema (JSON Schema) y, sobre todo, una description.

La description es la forma principal en que Claude decide qué herramienta utilizar, no el nombre. Una buena descripción indica el propósito de la herramienta, sus valores de retorno, los formatos de entrada con ejemplos y cuándo NO debe utilizarse. Las descripciones vagas o superpuestas provocan un enrutamiento incorrecto. Mantenga el conjunto reducido: lo óptimo son aproximadamente 4–5 herramientas por agente; añadir más de 18 perjudica la fiabilidad de la selección.

tool_choice controla si Claude llama a una herramienta y cómo lo hace:

• {"type": "auto"}: Claude decide si responde con texto o llama a una herramienta (valor predeterminado).
• {"type": "any"}: Claude DEBE llamar a alguna herramienta. Así se garantiza una salida estructurada.
• {"type": "tool", "name": "X"}: obliga a utilizar una herramienta específica.

Use any o una herramienta obligatoria cuando necesite un resultado legible por máquinas en cada ocasión; use auto en conversaciones abiertas en las que a veces sea correcta una respuesta sencilla.

Cada respuesta incluye un stop_reason que indica qué debe hacer a continuación. Los arquitectos toman decisiones basándose en él; nunca analizan el texto en busca de palabras como "hecho".

• "end_turn": Claude ha terminado de forma natural; el turno está completo.
• "tool_use": Claude quiere ejecutar una herramienta; ejecútela, añada el resultado y continúe.
• "max_tokens": la salida se ha truncado por alcanzar el límite.
• "stop_sequence": se ha encontrado una cadena de detención configurada.

Este único campo es la señal de control de todo el bucle agéntico.

Las herramientas, messages y stop_reason se combinan en el patrón principal: solicitud → inspeccionar stop_reason → si es tool_use, ejecutar las herramientas y añadir los resultados al historial → repetir hasta end_turn.

Como la API no tiene estado, debe añadir la solicitud de herramienta del asistente Y el resultado de la herramienta de nuevo a messages antes de la siguiente llamada. La terminación depende de stop_reason; las decisiones las toma el modelo. Cualquier límite de iteraciones que añada es una red de seguridad, nunca el mecanismo de detención principal.

La ausencia de estado no es una limitación que deba evitarse, sino el diseño que hace que Claude sea predecible y escalable. Como el modelo no conserva ningún estado oculto, la solicitud es la verdad completa: los mismos seis campos y el mismo historial producen el mismo comportamiento.

Por eso la gestión del contexto es una disciplina propia. A medida que crece el historial, reduzca las salidas detalladas de las herramientas a los campos relevantes, resuma los turnos antiguos y conserve sin cambios los datos transaccionales críticos (identificadores, importes y fechas) en un bloque específico, porque el modelo solo conoce lo que vuelve a incluir en messages.

Una solicitud de producción rara vez consta únicamente de un modelo y un prompt. Un turno de un agente de soporte combina los seis campos: un model seleccionado mediante enrutamiento, un max_tokens seguro, un system con las reglas, el historial completo de messages, un conjunto reducido de tools y un tool_choice adecuado para la tarea.

Si observa estos seis campos en cualquier solicitud, podrá predecir exactamente cómo se comportará; esa es la perspectiva del arquitecto.

Ahora tiene el modelo mental de arquitecto para una solicitud a Claude:

• model — capacidad frente a coste frente a latencia; seleccione la ruta según la tarea.
• max_tokens — límite máximo de salida aplicado; stop_reason: "max_tokens" significa que la salida se truncó.
• system — persona y reglas persistentes; manténgalas estables.
• messages — el historial COMPLETO, reenviado en cada turno, porque el modelo no conserva ningún estado.
• tools — las descripciones determinan la selección; mantenga unas 4 o 5 herramientas bien delimitadas.
• tool_choice — auto / any / forzada; use any para garantizar una salida estructurada.

Y el bucle que las conecta: condúzcalo mediante stop_reason (end_turn frente a tool_use), nunca analizando el texto. Si domina estos conceptos, el resto de la certificación se asentará sobre una base sólida.