Ingeniería de bucles: Creación de bucles de agente con verificadores y reglas de detención.
Una guía práctica para crear cuatro bucles de agente apilados: conceptos básicos de ReAct, calificadores con rúbricas, enrutamiento con LangGraph, un contrato de bucle, desencadenantes de eventos, método de escalada por colinas y medidas de protección contra fallos.
La mentalidad detrás de todo esto es fácil de explicar. Deje de dar instrucciones a la IA una por una y diseñe el bucle en el que opera. La idea clave es que el verificador, más que el modelo, limita lo en lo que se puede confiar; la imagen a tener en mente son cuatro bucles anidados entre sí. Así es como construirlo: las partes de un bucle, el código para cada capa, las formas en que los bucles fallan y las reglas de detención que evitan que agoten su presupuesto. Al final tendrá suficientes conocimientos como para permitir que un bucle prepare una solicitud de integración mientras usted duerme.
Los ejemplos de código siguen las APIs documentadas, los IDs de los modelos son marcadores de posición, y cualquier fragmento que sea solo pseudocódigo lo indica mediante un comentario al principio. Hay un ejemplo que se repite constantemente, el típico punto de partida en este campo: un bucle de programación que reproduce una prueba fallida, la corrige, hace que otra entidad revise esa corrección y abre un borrador de solicitud de integración.
Las cinco partes de un bucle
Sea cual sea el framework que utilice, un bucle funcional siempre se compone de cinco elementos. Si falta uno, el bucle pierde rumbo, se detiene o continúa indefinidamente.
- Un desencadenante. Lo que lo inicia, ya sea un mensaje humano, una actualización programada, un webhook o una nueva fila de tabla.
- Un objetivo que la máquina pueda verificar. “Hacer que las pruebas pasen” cumple este requisito, mientras que “mejorar el código” no. Si el software no puede determinar si se ha alcanzado el objetivo, el bucle tampoco podrá hacerlo.
- Herramientas que brindan retroalimentación real. El agente debe actuar sobre el entorno y observar los resultados ejecutando código, leyendo stderr o llamando a una API.
- Estado ligero y gestionado. Mantenga el objetivo, una zona de trabajo temporal y un registro de lo que se ha intentado. Un estado excesivo es la causa por la cual los bucles se ralentizan, se desvían y sobrepasan su ventana de contexto.
Planifique tres salidas y no dos. Éxito: el verificador aprobó, así que proceda con el envío. Rendición: se agotó el presupuesto o el límite de iteraciones, por lo que debe detenerse y resumir lo que queda. Transferencia: el agente se enfrentó a una decisión que solo debería tomar un humano, por lo que se escala el problema. Parte de diseñar un buen bucle es reconocer las llamadas que no debería realizar por sí mismo.
Bucle 1: el bucle del agente
En el centro se encuentra el ciclo que ya ejecutan todos los agentes, el patrón ReAct de 2022: pensar, actuar llamando a una herramienta, observar el resultado y repetir hasta finalizar. En 2026 está diseñado intencionalmente y ya no se gestiona manualmente. En su forma más simple consiste en una sola llamada a función:
from langchain.agents import create_agent
def run_tests() -> str:
"""Run the project's test suite and return the raw output."""
…
agent = create_agent(
model="anthropic:claude-opus-5",
tools=[run_tests],
system_prompt="You are a careful Python engineer. Fix failing tests.",
)
# create_agent returns a graph that calls tools in a loop, repeating
# until the model replies with no tool calls. The loop runs on .invoke()
Esa llamada breve oculta un bucle, y deberías poder imaginártelo. A continuación se muestra la misma estructura de control en pseudocódigo, sin ningún framework. Ten en cuenta que cada salida está delimitada:
# PSEUDOCODE - shows the control structure a harness implements.
# The helper names below are yours to supply, not a real library API.
def run_loop(goal):
state = init_state(goal) # goal + scratchpad + attempt log
for step in range(MAX_STEPS): # hard cap: never loop forever
thought = model.reason(state) # ReAct: reason…
action = model.choose_action(state) # …then pick a tool call
result = tools.execute(action) # touch the real environment
state = update(state, thought, action, result)
state = compact(state) # keep context under budget
if verifier.passes(state): # deterministic check = reward
return success(state)
if no_progress(state) or budget.exhausted():
return escalate_to_human(state) # third exit: hand-off
return escalate_to_human(state)
De todas las formas que hay aquí, recuerda esta. Las demás son versiones mejoradas de ella.
Bucle 2: agregar un verificador
Un agente simple decide por sí mismo cuándo ha terminado, y confiar en eso es la forma de obtener éxitos falsos. Por lo tanto, el agente se envuelve en un evaluador que comprueba su trabajo según una rúbrica. Cuando el trabajo falla, la crítica vuelve a procesarse y el bucle continúa hasta alcanzar un límite máximo. El middleware de verificación se encuentra en el paquete deepagents.
from deepagents import RubricMiddleware, create_deep_agent
from langchain.messages import HumanMessage
from langgraph.checkpoint.memory import InMemorySaver
RUBRIC = """
- All tests pass in run_tests
- No test is skipped or deleted to force a pass
"""
agent = create_deep_agent(
model="anthropic:claude-opus-5",
system_prompt="You are a careful Python engineer.",
middleware=[
RubricMiddleware(
model="anthropic:claude-haiku-4–5", # a cheap grader is fine
system_prompt="Grade against the rubric. Be strict.",
max_iterations=5, # the stop rule (default is 3)
),
],
checkpointer=InMemorySaver(),
)
# The rubric is passed at invoke time - not to the constructor.
result = agent.invoke(
{
"messages": [HumanMessage("Make the failing tests pass.")],
"rubric": RUBRIC,
},
config={"configurable": {"thread_id": "fix-tests-session"}},
)
Así es como funciona. Cada vez que el agente está a punto de terminar, un subagente evaluador separado lee la transcripción según la rúbrica. Un veredicto de needs_revision vuelve los comentarios a la conversación como un HumanMessage, y el agente continúa. Las únicas salidas posibles son satisfied, failed, max_iterations_reached y grader_error, por lo que el bucle se cierra y siempre termina. Si el evaluador necesita realizar sus propias verificaciones reales, proporcionadle herramientas en forma de instancias BaseTool.
Existen dos tipos de verificadores, y elegir bien uno es la clave del proceso.
- Determinístico: ejecuta las pruebas, valida el esquema y confirma la puntuación. Es económico, rápido e imposible de manipular, por lo que pruebe estos primero.
Conviértelo en un grafo
Cuando una tarea deja de ser trivial, un grafo explícito es mejor que un bucle oculto: los nodos, las aristas y el lugar donde se decide detenerse son todos visibles. Un agente de investigación cabe en tres nodos, siendo cada decisión de detención tomada por el router:
from typing import Literal, TypedDict
from pydantic import BaseModel, Field
from langgraph.graph import END, StateGraph
class ResearchState(TypedDict):
question: str
draft: str
verdict: str
feedback: str
iterations: int
class Verdict(BaseModel):
status: str = Field(description='"verified" or "needs_work"')
feedback: str = Field(description="claims lacking support, if any")
def decide(state: ResearchState) -> Literal["research", "__end__"]:
if state["verdict"] == "verified": # success exit
return "__end__"
if state["iterations"] >= MAX_ITERATIONS: # surrender exit
return "__end__"
return "research" # else: loop again with the feedback
builder = StateGraph(ResearchState)
builder.add_node("research", research_node) # generator
builder.add_node("verify", verify_node) # verifier
builder.add_edge("research", "verify")
builder.add_conditional_edges(
"verify", decide, {"research": "research", "__end__": END}
)
builder.set_entry_point("research")
graph = builder.compile()
No aparece ninguna instrucción inteligente en ese código. La inteligencia radica en la estructura: un nodo genera, otro verifica, y un enrutador convierte el resultado en una nueva oportunidad con retroalimentación o en una detención. LangGraph trata los marcadores __end__ y END como si fueran lo mismo.
El contrato del bucle
Aquí es donde el cambio de enfoque se vuelve concreto. En lugar de escribir instrucciones, se escribe una especificación de “finalización”, que incluye una función de recompensa además de una regla de detención. Ese es el artefacto que se revisa, compara y guarda:
Objetivo: realizar una compilación CI en verde en la rama payments-refactor. Se considera completado cuando todas las pruebas pasan y ninguna fue omitida o eliminada para engañar. Pasos: leer la prueba que falló, corregir la causa probable y ejecutar nuevamente. Memoria: un registro de los enfoques ya intentados, para que nada se repita. Se detiene al obtener un resultado en verde abriendo una propuesta de PR preliminar, después de seis intentos resumiendo lo que queda por hacer, o siempre que el trabajo afecte la lógica de autenticación o pagos, pasándolo a otra persona.
Ninguna instrucción fue enviada al modelo. Lo que se escribió fue el objetivo, las verificaciones, la regla de memoria y las tres salidas posibles; ese contrato constituye la ingeniería de bucles.
Bucles 3 y 4: apilamiento hacia afuera
Un solo bucle bien construido ya ayuda. Las ventajas se multiplican cuando se envuelven más bucles alrededor de él, cada uno ejecutándose a un ritmo más lento. Los bucles 1 y 2 realizan el trabajo correctamente, mientras que los bucles 3 y 4 lo hacen continuo y automejorable.
Bucle 3: eventos
Un evento externo convierte tu bucle de una herramienta que se llama en un servicio que se ejecuta por sí mismo. También es el lugar natural para incluir una etapa de aprobación humana antes de que cualquier cosa sea enviada:
# Loop 3: an event turns the loop into a service
from pydantic import BaseModel
class CIEvent(BaseModel):
branch: str
@app.post("/webhook/ci-failed")
def on_ci_failure(event: CIEvent):
if not event.branch.startswith("fix/"): # cheap triage first
return {"skipped": True}
result = agent.invoke(
{
"messages": [HumanMessage(
f"Fix the failing test on {event.branch}.")],
"rubric": TEST_GREEN_RUBRIC,
},
config={"configurable": {"thread_id": event.branch}},
)
open_draft_pr(result) # a human approves the merge, not the loop
return {"opened_pr": True}
Bucle 4: escalada de colinas
El bucle más externo es el más lento y actúa sobre el propio bucle. Cada ejecución deja una huella. Un agente de análisis lee esas huellas, detecta los fallos que se repiten constantemente y sugiere modificaciones en el sistema: la instrucción, las herramientas, la rúbrica que revisan los humanos. Imagina la flecha de retorno: en lugar de enviar información solo al inicio, llega hasta el bucle interno y lo modifica. El sistema está mejorando al propio sistema.
Una precaución: los bucles externos multiplican todo lo que hay dentro de ellos. Úsalos solo una vez que el verificador interno sea sólido, porque un cuarto bucle alrededor de un verificador débil simplemente automatiza información errónea a gran escala.
Por qué esto se considera ingeniería
Las barreras de protección pueden parecer trámites burocráticos. Dejan de parecérselo en cuanto se considera al agente como un controlador de retroalimentación de bucle cerrado, una relación que mantiene una correspondencia punto por punto. El objetivo es el valor de referencia, el agente es el controlador, y las herramientas junto con el entorno conforman la planta. El verificador actúa como sensor, y su veredicto de “necesita trabajo” es la señal de error que activa la siguiente corrección. Una tarea completada significa convergencia. El controlador es impulsado por la diferencia entre el valor de referencia y la lectura del sensor, ya sea que la planta sea un motor a reacción o un conjunto de pruebas.
El mismo vocabulario describe dos maneras en que se interrumpe un bucle. Puede oscilar, repitiendo indefinidamente una misma solución, o divergir, alejándose del objetivo mientras se agota el dinero. Las medidas de control son simplemente las condiciones de estabilidad que lo mantienen dentro de límites, y la regla más importante es que el sistema debe garantizar la terminación del proceso, algo en lo cual no se puede confiar al agente.
Un día con los cuatro bucles
Observe cómo funcionan los cuatro bucles a lo largo de una mañana. A las 09:14 falla una prueba relacionada con payments-refactor y se dispara un webhook, lo cual corresponde al bucle 3, sin que nadie escriba nada. Durante los siete minutos siguientes, el agente lee el error, aplica parches, vuelve a ejecutar la prueba, lee el nuevo error y vuelve a aplicar parches, manteniendo un registro de los intentos (bucle 1). Después de cada ronda, un evaluador determinista ejecuta todo el conjunto de pruebas y verifica que no se haya saltado nada para forzar una aprobación (bucle 2). La cuarta ronda finaliza con resultado positivo.
A las 09:22 el bucle finaliza correctamente, con un borrador de PR que muestra qué cambió y por qué. Un humano debe aprobarlo porque el cambio afecta los pagos. Durante la noche, el bucle de detección de problemas identifica que este es el tercer error relacionado con zonas horarias de la semana y elabora una nueva verificación según las normas, la cual pasa por tu revisión (bucle 4). La ejecución de mañana comenzará de manera más inteligente que la de hoy.
Dormiste casi todo el tiempo. Por la mañana hay un borrador de PR y una decisión que tomar, pero no hay teclado al que golpear.
Cuando los bucles fallan
Los bucles amplifican, y la amplificación funciona en ambas direcciones. Cada modo de fallo afecta al bucle en un punto específico y cuenta con una medida de protección estándar, con un tema recurrente: lo que genere no debe también evaluar. La protección más económica es ejecutar el verificador con entradas conocidas como buenas y conocidas como malas antes de dejar el bucle sin supervisión. Asegúrese de que rechace las malas, ya que un verificador no probado no es más que una opinión acompañada de un presupuesto.
Cuándo no construir un bucle
Apresurarse por aplicar un bucle a todo es en sí mismo un modo de fallo. Manténgalo como una sola llamada en estas situaciones:
- Una sola pasada es suficiente, como en el caso de un resumen, una traducción o una extracción limpia. Un bucle solo añade costos y latencia.
- No se puede verificar ningún objetivo. Sin una forma de comprobar que algo está “terminado”, no hay señal de error, lo que deja un bucle abierto que sigue gastando dinero.
La ingeniería de bucles implica saber qué problemas merecen un bucle, al igual que saber cómo construir uno.
Córralo como si fuera a mantener el trabajo
Esos son los herramientas: anatomía, bucle de agente, verificador, gráfico, contrato, bucles externos y catálogo de fallos. Equipa el bucle con un verificador sólido, una parada definitiva y límites que no pueda superar. Añade puntos de control humanos donde las consecuencias sean reales, y ten en cuenta que el hecho de que un bucle proporcione una solución no significa que lo entiendas. Luego déjalo funcionar, como lo haría alguien que pretende seguir siendo ingeniero y no solo la persona que lo pone en marcha.
El siguiente nivel
Hay una pregunta que vale la pena hacer antes de dejar un bucle sin supervisión: ¿hasta qué punto puede ser débil un verificador y aún así mostrar un resultado positivo? Se creó un punto de referencia para averiguarlo. Este registro registra los casos de manipulación de recompensas y evalúa las configuraciones de control según cuántos intentos de manipulación permiten pasar. Una configuración de control que ignora el informe del propio agente y vuelve a ejecutar el conjunto de pruebas, que es la verificación determinística sugerida anteriormente como primera opción, no detuvo ninguno de los ocho intentos. Volver a ejecutar el conjunto de pruebas solo confirma que se cumplió la condición de recompensa, y eso es exactamente lo que logra una manipulación de recompensas.
Así que, si el verificador limita el sistema, la habilidad escasa que surge a continuación es obvia: diseñar, versionar y mejorar las propias verificaciones. La gente lo denomina ingeniería de evaluación, la tarea de establecer los criterios que el bucle debe superar. Un verificador es una habilidad específica dentro de un único bucle. La ingeniería de evaluación abarca muchos de ellos, a través de los conjuntos de datos y las rúbricas que revelan si el sistema en su conjunto está mejorando o empeorando.
Reforzar una etapa de verificación es como subir una escalera, y su punto más alto es impredecible. Resulta que la mejor verificación no es un código sofisticado, sino solo unas pocas afirmaciones que al agente nunca se le permitió ver. Por lo tanto, el límite de la verificación se sitúa en un lugar delicado. Depende menos de cuán bien esté construida una etapa y más de la calidad de los datos reservados y de si se evita que vuelvan a filtrarse al bucle.
Leer más
- Ingeniería de bucles: Diseña el bucle que guía a tu agente de IA — Por qué el verificador es el cuello de botella en los bucles de agentes, cómo se organizan cuatro bucles anidados y qué medidas de seguridad y puntos de control humano mantienen seguro a un agente de codificación autónomo.
- Ingeniería de bucles: Cuatro bucles anidados para agentes de IA auto-mejorables — Cómo cuatro bucles de control anidados (ReAct, reintentos, cola y método de escalada por colinas), junto con un juez, un medidor de presupuesto y una verificación contra modificaciones, hacen que un agente sea fiable, como se demuestra en la evaluación de seguros.