El bucle agéntico: seguir mientras stop_reason sea tool_use

Un agente es un loop: le mandás un pedido a Claude, Claude pide usar una herramienta, tu código la ejecuta, le devolvés el resultado y vuelve a empezar. La pregunta del examen casi siempre es la misma: ¿cuándo sigue y cuándo termina?

El ciclo

El bucle agéntico (agentic loop) tiene cuatro pasos:

1. mandás la request con el historial completo (la API no guarda estado: Claude solo ve lo que está en messages);
2. mirás el motivo de corte (stop_reason) de la respuesta;
3. si es "tool_use", ejecutás cada herramienta pedida y agregás los resultados al historial;
4. si es "end_turn", Claude terminó y el loop corta.

stop_reason es la señal estructurada de la API. El texto de la respuesta nunca decide.

Cómo se arma el historial

El orden es siempre el mismo: mensaje user, mensaje assistant con el bloque tool_use y otro mensaje user con el resultado de herramienta (tool_result).

• Cada tool_result lleva el tool_use_id de la llamada a la que responde. Sin el mensaje del assistant antes, la API no encuentra a qué llamada corresponde.
• Si Claude pidió tres herramientas en una sola respuesta, van tres tool_result juntos en un único mensaje de usuario. Dejar uno sin responder da error.
• Si el resultado se imprime en un log pero no se agrega al historial, Claude nunca lo ve y lo vuelve a pedir: así nacen los loops que llaman a get_order para siempre.
• Una falla de la herramienta no corta el loop: vuelve como tool_result con is_error: true y una descripción clara, y Claude decide si reintenta, usa otra herramienta o le explica el límite al usuario.

Otros valores de stop_reason

"max_tokens" significa que la respuesta se cortó por el límite de largo, no que la tarea terminó. Se maneja aparte: subir el límite o pedirle que continúe. Tratar “todo lo que no es tool_use” como fin entrega respuestas cortadas.

Modelo o guion fijo

En una decisión dirigida por el modelo (model-driven decision-making), Claude elige qué herramienta llamar y cuándo parar según lo que va encontrando. Un guion fijo que corre las mismas cinco llamadas para cada consulta desperdicia tiempo y no se adapta. La excepción son los pasos con requisitos estrictos (verificar identidad, aprobar un pago): esos se garantizan en código, como se vio en la lección 1.

Las trampas típicas

• Leer el texto para decidir: buscar frases como “listo” o “I’ll now…” es interpretar lenguaje natural, ambiguo y frágil. Una misma respuesta puede traer texto y un tool_use; con stop_reason: "tool_use" ese texto es un comentario intermedio.
• Tomar la ausencia de texto como fin: tampoco dice nada.
• Un tope de iteraciones como control principal: corta tareas largas y no arregla la causa. Un tope sirve solo como red de seguridad (safety net) contra loops descontrolados, y conviene registrar los casos que llegan a él para investigar.
• Forzar tool_choice: "any" para que “siga trabajando”: le saca a Claude la posibilidad de terminar con texto.

Si la respuesta dice "end_turn" pero el texto anuncia una búsqueda que nunca pasó, end_turn manda: el loop termina y se investiga el prompt.

En el examen

Si el escenario describe un loop que termina antes de tiempo, que no termina nunca o que repite la misma llamada, buscá la opción que pone a stop_reason como control y agrega los resultados al historial con su tool_use_id. Descartá parsear texto, topes como solución y mínimos de vueltas.