Ya no deberías limitarte a escribir prompts para agentes de codificación. Deberías diseñar bucles que hagan que esos agentes se autocorrijan. Los equipos que sacan valor real de los agentes de codificación de IA no tratan al agente como un chat. Lo tratan como un trabajador dentro de un flujo controlado por pruebas, contratos y señales deterministas.
En resumen
Un bucle de agente de codificación ejecuta al agente repetidamente:
- genera un cambio;
- ejecuta el código;
- verifica el resultado contra una señal estricta;
- devuelve el fallo al agente;
- repite hasta que la verificación pasa o se alcanza un límite.
El agente no es la parte difícil. La puerta de verificación sí lo es.
Una puerta vaga como “revísalo, algo parece mal” produce deriva. Una puerta determinista —una prueba fallida, un contrato roto, una diferencia de esquema— produce convergencia.
Para trabajo de API y backend, tus pruebas automatizadas y verificaciones de contrato deben estar en el centro del flujo agéntico. Las pruebas de API no son una fase final: son el mecanismo que guía al agente.
De escribir prompts a diseñar bucles
El flujo manual típico es este:
- escribes un prompt;
- lees la respuesta;
- pruebas el código;
- encuentras un error;
- pegas el error en el chat;
- repites.
El problema: tú eres el bucle.
El agente puede generar código en segundos, pero queda bloqueado mientras tú cambias de contexto, ejecutas comandos y decides qué decirle después.
Diseñar un bucle invierte el control:
- el agente escribe código;
- un script ejecuta la verificación;
- si falla, el error vuelve automáticamente al agente;
- si pasa, el bucle termina;
- si agota intentos, escala a un humano.
El artículo de Anthropic sobre la construcción de agentes efectivos apunta en la misma dirección: el valor no viene de un único prompt perfecto, sino del entorno que conectas alrededor del modelo.
La pregunta cambia de:
¿Qué debo decirle al agente?
a:
¿Qué bucle haría que el agente reciba la señal correcta en cada iteración?
Qué es realmente un bucle de agente de codificación
Un bucle útil tiene cinco piezas.
1. Especificación de tarea
Debe definir qué significa “hecho”.
Mal:
Haz que el endpoint de pedidos funcione.
Mejor:
Implementa POST /orders.
Debe:
- devolver 201 cuando el pedido se crea correctamente;
- validar el cuerpo contra el esquema OpenAPI;
- rechazar campos faltantes con 422;
- devolver un cuerpo que coincida con OrderResponse;
- no modificar la especificación OpenAPI.
2. Agente
El modelo más sus herramientas:
- leer archivos;
- escribir archivos;
- ejecutar comandos;
- inspeccionar logs;
- consultar documentación o endpoints.
Esta es la parte visible, pero no la más importante.
3. Acción
El agente realiza un cambio y el sistema lo ejecuta:
- correr tests;
- compilar;
- levantar un servicio;
- hacer una petición HTTP;
- validar un esquema;
- ejecutar una suite de contrato.
4. Puerta de verificación
Una comprobación determinista que devuelve éxito o fallo con una razón concreta.
Ejemplos:
-
pytestdevuelve exit code distinto de cero; - el compilador falla;
- una respuesta no coincide con el JSON Schema;
- un endpoint devuelve
500donde se esperaba422; - la implementación no respeta OpenAPI.
5. Condición de terminación
El bucle debe detenerse cuando:
- la puerta pasa;
- se alcanza
MAX_ITERATIONS; - se supera un presupuesto;
- el error requiere intervención humana.
Sin salida, no tienes un flujo de trabajo: tienes un proceso descontrolado.
El patrón mínimo en pseudocódigo
task = load_spec("orders-endpoint.md")
last_result = None
for attempt in range(MAX_ITERATIONS):
agent.run(task, feedback=last_result)
result = run_verification()
if result.passed:
break
last_result = result.failures
else:
escalate_to_human(last_result)
El patrón completo es simple:
- el agente genera;
- la puerta juzga;
- el fallo se convierte en el siguiente prompt;
- el bucle continúa hasta estar en verde o rendirse.
La técnica que algunas personas llaman “Ralph” es una versión de esto con un MAX_ITERATIONS alto y una especificación breve. Si ya leíste nuestro análisis sobre la arquitectura del arnés del agente, este es el arnés en su forma mínima.
Por qué el prompt único no escala
Un prompt único asume dos cosas:
- que el modelo acierta a la primera;
- que tú detectarás lo que hizo mal.
Ambas fallan en trabajo real.
Un modelo puede generar un endpoint que:
- compila;
- parece correcto;
- devuelve una respuesta plausible;
- pero falla en un caso límite;
- o devuelve el código de estado incorrecto;
- o rompe el contrato OpenAPI.
En un chat, quizá no lo notes hasta producción. El modelo puede decir “listo” sin tener una señal real de que está listo.
Un bucle evita aceptar la opinión del modelo sobre su propio trabajo.
La regla es:
El agente no decide si terminó. La puerta lo decide.
Si las pruebas están en rojo, la tarea no está terminada. El fallo se convierte en la siguiente entrada del agente.
Esto también mejora la productividad. En vez de observar un agente manualmente, puedes ejecutar varios bucles en paralelo, cada uno con su propia tarea y su propia puerta. Ese es el salto descrito en nuestro artículo sobre flujos de trabajo de agente dinámicos y paralelos: escalas añadiendo bucles, no escribiendo prompts más rápido.
La parte que todos subestiman: la puerta de verificación
La mayoría de los flujos agénticos fallidos no fallan porque el modelo sea débil. Fallan porque la señal de feedback es mala.
Compara estas dos respuestas al agente.
Mala señal:
Algo parece raro. Revisa la implementación.
Buena señal:
Test failed: POST /orders without customer_id
Expected:
HTTP 422
Actual:
HTTP 500
Error:
ValidationError was not handled before creating the order.
La segunda señal le dice al agente qué corregir. La primera lo obliga a adivinar.
Las puertas deterministas convergen. Las puertas difusas se desvían.
Qué hace buena a una puerta
Una buena puerta debe cumplir estas condiciones.
Es binaria y reproducible
Misma entrada, mismo resultado.
pass / fail
No debe depender de una evaluación subjetiva del modelo.
Falla con una razón específica
Debe producir información accionable:
- nombre de test;
- diferencia esperado vs actual;
- línea de error;
- código de estado;
- campo inválido;
- endpoint afectado;
- contrato incumplido.
El agente no puede editarla libremente
Si el agente puede modificar la prueba para hacerla pasar, la puerta no sirve.
Protege:
- archivos de test;
- especificaciones OpenAPI;
- fixtures críticos;
- contratos;
- snapshots aprobados.
Es rápida
Una suite de 20 minutos no sirve como bucle interno.
Usa una puerta rápida para iterar y deja verificaciones más pesadas para CI o pre-merge.
Ya existe en tu stack
No necesitas inventar señales nuevas. Ya tienes muchas:
- unit tests;
- type checkers;
- linters;
- compiladores;
- validadores JSON Schema;
- pruebas de contrato;
- pruebas de API;
- suites de integración.
Si todavía no tienes esa capa clara, esta guía sobre qué son realmente las pruebas automatizadas es una buena base antes de conectarlas a un bucle.
Para APIs y backend, tu suite de pruebas es el bucle
Cuando un agente implementa un endpoint, la verdad no es su resumen final. La verdad es el comportamiento observable del endpoint.
Para una API, puedes verificar automáticamente:
- códigos de estado;
- cuerpo de respuesta;
- validación de entrada;
- autenticación;
- autorización;
- compatibilidad con OpenAPI;
- campos requeridos;
- tipos de datos;
- errores esperados;
- contratos entre servicios.
Eso significa que tu suite de pruebas de API ya tiene la forma correcta para actuar como puerta de verificación.
Bucle concreto para implementar un endpoint
Un flujo práctico para endpoints puede verse así:
- El agente lee la especificación de tarea y el archivo OpenAPI.
- El agente implementa o modifica el endpoint.
- El arnés levanta el servicio.
- La suite de API ejecuta casos positivos y negativos.
- La puerta valida estado HTTP, cuerpo, esquema y contrato.
- Los fallos vuelven al agente en formato estructurado.
- El agente corrige.
- El bucle repite hasta verde o hasta agotar intentos.
- Un humano revisa el diff final.
Ejemplo de feedback útil:
Contract failure: POST /orders
Case:
missing customer_id
Expected:
HTTP 422
Actual:
HTTP 201
Schema:
ErrorResponse
Actual body:
{
"id": "ord_123",
"total": 99.5
}
Action:
Reject requests without customer_id before creating the order.
Otro ejemplo:
Schema mismatch: GET /orders/{id}
Field:
total
Expected:
number
Actual:
string
Actual value:
"42.50"
La clave es que el feedback del paso 6 es generado por máquina, no por intuición.
Las pruebas de contrato y esquema-primero importan más en este patrón porque la especificación OpenAPI se convierte en la fuente de verdad compartida por el agente y por la puerta.
Este es el rol de Apidog en un flujo agéntico: centralizar diseño de API, esquema, mock server y pruebas automatizadas en un solo espacio. Así, la especificación y la puerta permanecen alineadas.
Puedes apuntar el bucle a un escenario de prueba de Apidog, recibir aprobado/fallo con validación de esquema y usar el servidor simulado para sustituir dependencias que todavía no existen. Los equipos que trabajan con este patrón también pueden conectar herramientas del agente mediante el depurador de agentes de IA de Apidog, de forma que el agente inspeccione endpoints como lo haría un tester humano.
Si quieres construir la puerta visualmente en lugar de crear tu propio runner, puedes descargar Apidog.
Construye un bucle API autocorregible mínimo
No necesitas un framework complejo. Necesitas:
- una especificación;
- un comando de prueba;
- un agente con acceso limitado;
- un script que conecte todo.
Paso 1: escribe la especificación
Crea un archivo de tarea:
# Tarea: implementar POST /orders
Implementa el endpoint POST /orders según openapi.yaml.
Requisitos:
- devolver 201 cuando el pedido sea válido;
- devolver 422 si falta customer_id;
- devolver 422 si items está vacío;
- devolver ErrorResponse en errores de validación;
- devolver OrderResponse en éxito;
- no modificar openapi.yaml;
- no modificar tests/.
Mantén la especificación concreta y verificable.
Paso 2: define la puerta como un comando
Cualquier comando sirve si:
- devuelve
0cuando pasa; - devuelve distinto de
0cuando falla; - imprime errores útiles.
Ejemplo con Apidog CLI:
apidog run ./tests/orders-suite --reporter json > result.json
Ejemplo con pytest:
pytest tests/api/test_orders.py --json-report --json-report-file=result.json
Ejemplo con Newman:
newman run orders.postman_collection.json \
--environment local.postman_environment.json \
--reporters cli,json \
--reporter-json-export result.json
Paso 3: conecta el bucle
import subprocess
import json
MAX_ITERATIONS = 8
def run_agent(task, feedback=None):
"""
Implementa esta función usando tu agente:
Claude Code, Cursor, Codex, un agente propio, etc.
"""
prompt = task
if feedback:
prompt += "\n\nFallos de la última ejecución:\n"
prompt += feedback
# Ejemplo conceptual:
# agent.run(prompt)
print("Running agent with prompt:")
print(prompt)
def run_gate():
return subprocess.run(
[
"apidog",
"run",
"./tests/orders-suite",
"--reporter",
"json"
],
capture_output=True,
text=True
)
def parse_failures(stdout, stderr):
if stdout:
return stdout
return stderr or "La puerta falló sin salida capturada."
task = """
Implementa POST /orders según openapi.yaml.
No modifiques:
- openapi.yaml
- tests/
La tarea termina cuando la suite orders-suite pasa completa.
"""
feedback = None
for attempt in range(MAX_ITERATIONS):
print(f"Attempt {attempt + 1}/{MAX_ITERATIONS}")
run_agent(task=task, feedback=feedback)
gate = run_gate()
if gate.returncode == 0:
print(f"Verde en el intento {attempt + 1}")
break
feedback = parse_failures(gate.stdout, gate.stderr)
else:
print("La suite sigue en rojo. Escalando a un humano.")
print(feedback)
Este script hace lo esencial:
- ejecuta el agente;
- corre la puerta;
- captura el fallo;
- lo reutiliza como feedback;
- corta después de un número máximo de intentos.
Paso 4: protege la puerta
No permitas que el agente edite los archivos que definen la verdad.
Por ejemplo, en tu configuración de agente, excluye:
openapi.yaml
tests/
contracts/
fixtures/approved/
O ejecuta una verificación adicional:
git diff --exit-code openapi.yaml tests/
Si ese comando falla, el agente modificó la puerta.
Puedes integrarlo en el bucle:
def verify_gate_not_modified():
return subprocess.run(
["git", "diff", "--exit-code", "openapi.yaml", "tests/"],
capture_output=True,
text=True
)
Paso 5: limita costo e iteraciones
Siempre define límites:
MAX_ITERATIONS = 8
MAX_SECONDS = 900
MAX_COST_USD = 5
También registra cada intento:
runs/
attempt-01/
prompt.md
result.json
diff.patch
attempt-02/
prompt.md
result.json
diff.patch
Esto permite auditar si el bucle converge o solo consume tokens. Si necesitas optimizar gasto, estas notas sobre cómo reducir los costos de tokens del agente aplican directamente.
Errores comunes al diseñar bucles
1. Dejar que el agente evalúe su propio trabajo
Mal:
¿Terminaste? Responde sí o no.
Eso no es una puerta. Es una opinión.
Usa una verificación externa:
npm test
pytest
apidog run ./tests/orders-suite
go test ./...
mvn test
2. Usar una puerta demasiado débil
Si solo tienes tres tests superficiales, el agente optimizará para esos tres tests.
La calidad del bucle está limitada por la calidad de la puerta.
Añade casos negativos:
- campos faltantes;
- tipos incorrectos;
- autenticación ausente;
- permisos insuficientes;
- payloads límite;
- respuestas no conformes al esquema.
3. No tener condición de terminación
Nunca ejecutes un bucle sin límite.
Mínimo:
MAX_ITERATIONS = 8
Mejor:
MAX_ITERATIONS = 8
MAX_RUNTIME_SECONDS = 900
MAX_CHANGED_FILES = 20
4. Usar puertas lentas
Una suite de integración de 15 minutos puede ser útil en CI, pero no en un bucle interno.
Divide las puertas:
Puerta rápida:
- tests del endpoint;
- validación de esquema;
- contrato local;
- mocks.
Puerta completa:
- integración end-to-end;
- dependencias reales;
- regresión amplia;
- CI pre-merge.
5. Permitir especificaciones mutables
Si el agente cambia OpenAPI para que coincida con su implementación incorrecta, la prueba puede pasar por la razón equivocada.
Regla práctica:
La especificación es la constitución. El agente trabaja bajo ella, no sobre ella.
6. Darle una tarea gigante
Mal:
Construye todo el servicio de pedidos.
Mejor:
Implementa POST /orders.
Luego implementa GET /orders/{id}.
Luego implementa PATCH /orders/{id}/status.
Un endpoint por bucle suele converger mejor que una tarea masiva.
Estos patrones coinciden con lo que cubrimos en la conexión de herramientas en el flujo de trabajo agéntico, independientemente de si usas Claude Code, Cursor, Codex o un agente propio.
Checklist para tu primer bucle
Antes de ejecutarlo, verifica:
- [ ] La tarea define claramente qué significa “hecho”.
- [ ] Existe una puerta con salida binaria.
- [ ] Los fallos son específicos y legibles.
- [ ] El agente no puede editar tests ni especificaciones.
- [ ] Hay límite de iteraciones.
- [ ] Hay logs por intento.
- [ ] El bucle escala a humano si no converge.
- [ ] La puerta es lo bastante rápida para iterar.
- [ ] La especificación OpenAPI es la fuente de verdad.
- [ ] Los casos negativos están cubiertos.
Hacia dónde va esto
“Deja de escribir prompts, empieza a diseñar bucles” resume una tendencia más amplia.
La habilidad valiosa no es solo el prompt-craft. Es el loop-craft:
- escribir especificaciones claras;
- construir puertas deterministas;
- proteger contratos;
- definir límites;
- decidir qué puede tocar el agente;
- diseñar feedback accionable;
- conectar el bucle con CI y pruebas.
Eso está más cerca del diseño de sistemas que de la ingeniería de prompts.
También cambia el valor de las pruebas. Antes eran una red de seguridad. En un flujo agéntico, son el mecanismo de dirección.
Una buena cobertura de pruebas automatizadas convierte a un generador rápido pero poco fiable en un sistema que converge hacia un resultado correcto. Sin esa capa, solo generas código no verificado más rápido.
Conclusión
No mejores solo escribiendo mejores prompts para tu agente de codificación. Mejora diseñando el bucle que lo guía.
El agente genera. La puerta decide.
Para APIs, ya tienes los componentes principales:
- especificación OpenAPI;
- pruebas de API;
- validación de esquema;
- pruebas de contrato;
- CI;
- mocks;
- casos negativos.
Empieza pequeño:
- escribe una especificación concisa;
- apunta un bucle a una suite rápida de pruebas de API;
- protege la puerta;
- limita iteraciones;
- devuelve fallos estructurados al agente;
- revisa el diff final antes de fusionar.
Si quieres una puerta visual, consciente del esquema y compartible con el equipo, Apidog reúne diseño, mock server y pruebas automatizadas en un solo espacio de trabajo. Puedes descargarlo y convertir tus pruebas en la señal que dirige a tus agentes.
Top comments (0)