Agente multipaso con bucle de razonamiento
En esta página
Agente multipaso con bucle de razonamiento
Los agentes más potentes no se detienen tras una única llamada a una herramienta. Encadenan múltiples pasos de razonamiento, ajustan su estrategia en función de los resultados e iteran hasta alcanzar su objetivo. En esta lección aprenderás a construir estos agentes multipaso. Los ejemplos utilizan la familia GPT-5.6: mientras que la generación anterior requería cambiar de modelo para habilitar el razonamiento, ahora controlas este comportamiento mediante el parámetro de esfuerzo (effort) en el modelo que elijas.
El patrón planificar-ejecutar
Un agente multipaso comienza creando un plan y luego ejecuta cada paso. Esta separación es deliberada: el planificador no tiene herramientas y produce una estructura tipada, mientras que el ejecutor recibe este plan como hoja de ruta y simplemente lo sigue. Una solicitud vaga como «prepara la revisión trimestral para las cuentas clave» se convierte en una secuencia concreta de acciones —consultar el CRM, generar el informe, enviar el correo electrónico— antes de intentar cualquier acción.
from agents import Agent, Runner, function_tool
from pydantic import BaseModel
import json
class PlanAction(BaseModel):
steps: list[str]
objective: str
planner_agent = Agent(
name="Planner",
instructions="""Recibes una tarea compleja. Desglosala en pasos simples y ordenados.
Cada paso debe ser un elemento concreto y ejecutable.""",
model="gpt-5.6-sol", # Razonamiento avanzado para la planificación
output_type=PlanAction,
)
@function_tool
def search_crm(query: str) -> str:
"""Busca información de clientes en el CRM."""
return json.dumps({"customers": [
{"name": "Acme Corp", "revenue": 500000, "contract": "Enterprise"},
{"name": "TechStart", "revenue": 50000, "contract": "Starter"},
]})
@function_tool
def generate_report(title: str, content: str) -> str:
"""Genera un informe formateado."""
return f"Informe '{title}' generado correctamente ({len(content)} caracteres)"
@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
"""Envía un correo electrónico."""
return f"Correo enviado a {recipient}: {subject}"
executor_agent = Agent(
name="Executor",
instructions="""Ejecutas las tareas paso a paso.
Utiliza las herramientas disponibles para completar cada paso.
Si un paso falla, prueba un enfoque alternativo.""",
tools=[search_crm, generate_report, send_email],
model="gpt-5.6-terra",
)
async def process_complex_task(task: str):
# Paso 1: Planificar
plan = await Runner.run(planner_agent, task)
print(f"Plan: {plan.final_output.steps}")
# Paso 2: Ejecutar con el plan como contexto
execution_instructions = f"""Ejecuta los siguientes pasos en orden:
{chr(10).join(f'{i+1}. {e}' for i, e in enumerate(plan.final_output.steps))}
Objetivo: {plan.final_output.objective}"""
result = await Runner.run(executor_agent, execution_instructions)
return result.final_output
Agente de autocorrección
La planificación no es suficiente: en el mundo real, las herramientas fallan. La segunda forma de bucle permite al agente detectar sus propios errores y corregirlos. Todo depende de un detalle que a menudo se pasa por alto: la herramienta no lanza una excepción; devuelve un mensaje de error legible. El agente lo lee, se da cuenta de que olvidó la cláusula FROM, reescribe su consulta y lo reintenta, dentro del límite de tres intentos establecido en sus instrucciones.
from agents import Agent, Runner, function_tool
@function_tool
def execute_sql_query(sql: str) -> str:
"""Ejecuta una consulta SQL en la base de datos."""
# Simulación: algunas consultas fallan
if "DROP" in sql.upper():
return "ERROR: Las consultas destructivas están prohibidas."
if "SELECT" in sql.upper() and "FROM" not in sql.upper():
return "ERROR: Sintaxis SQL no válida - falta FROM."
return json.dumps({
"columns": ["name", "monthly_revenue", "region"],
"rows": [
["Acme Corp", 45000, "Île-de-France"],
["TechStart", 12000, "Rhône-Alpes"],
],
"result_count": 2
})
analyst_agent = Agent(
name="Data Analyst",
instructions="""Analizas datos ejecutando consultas SQL.
Si una consulta falla:
1. Analiza el mensaje de error
2. Corrige la consulta
3. Reintenta
Máximo 3 intentos por consulta.
Nunca uses DROP, DELETE ni TRUNCATE.""",
tools=[execute_sql_query],
model="gpt-5.6-terra",
max_turns=10, # Suficientes turnos para correcciones
)
result = Runner.run_sync(
analyst_agent,
"¿Cuál es el ingreso total por región?"
)
Observa que la prohibición de consultas destructivas aparece en dos lugares: en las instrucciones y en el código de la herramienta. La instrucción guía al modelo, pero solo la comprobación del lado del servidor en la herramienta garantiza que un DROP TABLE no se cuele nunca.
Patrón: cadena de agentes especializados
Para flujos de trabajo complejos, encadena varios agentes especializados en lugar de cargar un único agente con todas las responsabilidades. Cada eslabón tiene un rol claro: el recolector reúne la materia prima, el analista —equipado con un modelo de razonamiento— identifica tendencias y el redactor da formato a la salida. La ventaja es tanto educativa como operativa: cuando el informe final decepciona, sabes inmediatamente cuál de los tres agentes debes corregir.
from agents import Agent, Runner
collection_agent = Agent(
name="Data Collector",
instructions="Recopila todos los datos necesarios para el análisis.",
tools=[search_crm, execute_sql_query],
model="gpt-5.6-terra",
)
analysis_agent = Agent(
name="Analyst",
instructions="Analiza los datos recopilados e identifica tendencias.",
model="gpt-5.6-sol", # Razonamiento avanzado para el análisis
)
writing_agent = Agent(
name="Writer",
instructions="""Escribe un informe claro y estructurado en inglés
basado en el análisis proporcionado. Formato: introducción, puntos clave, recomendaciones.""",
model="gpt-5.6-terra",
)
async def analysis_pipeline(question: str):
# Paso 1: Recopilar datos
data = await Runner.run(collection_agent, question)
# Paso 2: Analizar
analysis = await Runner.run(
analysis_agent,
f"Analiza estos datos: {data.final_output}"
)
# Paso 3: Escribir el informe
report = await Runner.run(
writing_agent,
f"Escribe un informe basado en este análisis: {analysis.final_output}"
)
return report.final_output
Control de la profundidad del razonamiento
Todos estos bucles comparten una característica: podrían no detenerse nunca. El parámetro max_turns es tu principal salvaguarda y debes ajustarlo en función de la ambición de la tarea. Tres turnos bastan para un agente que se espera que responda al primer intento; veinticinco son necesarios para una exploración que consulta múltiples fuentes antes de concluir.
# Agente conservador: pocos turnos
simple_agent = Agent(
name="Simple Agent",
instructions="Responde en un único turno si es posible.",
model="gpt-5.6-terra",
)
result = await Runner.run(simple_agent, "Pregunta simple", max_turns=3)
# Agente complejo: muchos turnos
research_agent = Agent(
name="Deep Researcher",
instructions="Explora todos los ángulos antes de concluir.",
tools=[search_crm, execute_sql_query],
model="gpt-5.6-terra",
)
result = await Runner.run(research_agent, "Análisis completo del T1", max_turns=25)
Establece este valor observando tus trazas en lugar de adivinar: si tus ejecuciones reales terminan en seis turnos, un límite de veinticinco no protege contra nada.
Puntos clave
- El patrón planificar-ejecutar separa la planificación (modelo de razonamiento) de la ejecución
- Un agente de autocorrección analiza sus errores y ajusta su estrategia
- Las cadenas de agentes especializados permiten flujos de trabajo complejos y mantenibles
max_turnscontrola la profundidad del razonamiento y protege contra bucles infinitos- Reserva las capacidades de razonamiento avanzado para la planificación y el análisis