Katas Deterministic Agent Loop

Qué es

Un bucle agéntico que decide continuar o detenerse mirando SOLO el campo estructurado stop_reason que devuelve la API (tool_use vs end_turn), nunca la prosa que escribe el modelo. Cada iteración llama a create(...), inspecciona stop_reason y enruta: tool_use despacha la herramienta y reinyecta el tool_result; end_turn finaliza; cualquier otro valor (max_tokens, pause_turn, etc.) eleva un error explícito. Aplica a escenarios como Customer Support y Multi-Agent Research, donde el control del turno debe ser predecible.

Por qué importa (falla que evita)

Detener el bucle por heurística de texto convierte una frase casual del modelo ("task complete", "listo") en un halt silencioso a destiempo o, peor, en un bucle infinito cuando el modelo nunca pronuncia la frase esperada. El parseo de prosa es no determinista por construcción: depende del idioma, del tono y de la redacción del modelo. El control debe vivir en el contrato estructurado de la API, no en la superficie textual.

Modelo mental

• Cada iteración produce un stop_reason: tool_use → dispatch, end_turn → halt, otros → error explícito.
• El tool_result se reinyecta como role=user, manteniendo el contrato turn-by-turn de la conversación.
• max_tokens / pause_turn inesperados deben fallar fuerte (raise), nunca silenciosamente.
• El bucle se acota con un budget configurable (max_iterations) que eleva BudgetExceeded al excederse.
• La prosa del modelo es output para el humano, no señal de control para la máquina.
• Un turno con varios tool_use se coordina como un lote completo: paraleliza solo llamadas independientes, serializa dependencias y devuelve un resultado correlacionado por cada ID en un único turno inmediato; una llamada omitida también recibe is_error.
• Con Anthropic SDK Tool Runner, distingue historial automático de takeover manual, decide sobre el mensaje final acumulado cuando hay streaming, aplica hooks y compactación solo donde la matriz del SDK los soporta, y conserva max_iterations como límite externo.

Patrón correcto

while True:
    resp = create(...)
    if resp.stop_reason == "tool_use":
        dispatch(resp)
        continue
    elif resp.stop_reason == "end_turn":
        return resp
    else:
        raise UnhandledStop(resp.stop_reason)

Anti-patrón

DONE = ["task complete", "done", "listo"]
if any(p in text for p in DONE):
    return  # parsea prosa: halt silencioso o bucle infinito

Argumento de certificación

El control del bucle vive en stop_reason + budget + handlers tipados, no en heurísticas de texto. Una implementación certificada (1) enruta exclusivamente por stop_reason, (2) trata todo valor no manejado como error explícito, y (3) acota la ejecución con un budget configurable que eleva BudgetExceeded.

Para coordinación múltiple, la certificación exige además un ledger de todos los tool_use_id, una partición explícita entre llamadas independientes y dependientes, y un único turno de resultados completo. Para Tool Runner, exige ownership inequívoco del historial, hook previo al envío solo cuando exista, decisión posterior a get_final_message() o equivalente, matriz de compactación y política explícita para resultados is_error.

Eval gates

• parallel-multi-tool-coordination-loop: prueba lote múltiple, dependencias, paralelismo seguro, resultado único por ID y is_error para trabajo omitido.
• anthropic-sdk-tool-runner-deterministic-loop: prueba iteración del runner, historial automático/manual, hook, stream final, compactación, error y max_iterations sin control por prosa.

Cuándo activar

• Diseñar o revisar un bucle agéntico que llama a la API en iteraciones.
• Detectar control de flujo basado en parseo de texto ("done", "task complete").
• Definir condiciones de halt, manejo de tool_use/end_turn o límites de iteración.
• Controlar programmatic tool calling con resultados correlacionados, timeout explícito y budget finito, sin convertir allowed_callers en autorización ni la prosa en señal de halt.
• Coordinar varios tool_use con dependencias o ejecutar el Anthropic SDK Tool Runner bajo una política de historial, hooks, streaming, compactación y errores verificable.
• Triggers: deterministic loop, stop_reason, agent loop control, budget exceeded.

Skills relacionadas

• katas-pretooluse-guardrails
• katas-error-propagation-multi-agent
• katas-human-handoff-protocol
• claude-api-tool-runtime
• claude-api-server-tools

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output.