Arquitectura de agente: el bucle de razonamiento y herramientas
En esta página
Actualizado el 3 de noviembre de 2026: En
rechercher_produit, faltaban las comillas en las clavesprixystock, lo que provocaba unNameErroren la primera llamada a la herramienta.
Arquitectura de agente: el bucle de razonamiento y herramientas
Para construir agentes eficaces, debes comprender su arquitectura interna. Un agente de OpenAI funciona mediante un bucle de razonamiento: recibe una tarea, piensa, utiliza una herramienta, observa el resultado y decide si ha terminado o necesita continuar. Todo lo que hagas a continuación —declarar herramientas, establecer salvaguardas u orquestar varios agentes— se basa en este bucle.
El ciclo de vida del agente
Cada ejecución sigue seis pasos:
- Recepción: El agente recibe el mensaje del usuario y las instrucciones del sistema.
- Razonamiento: El modelo analiza la solicitud y decide la siguiente acción.
- Llamada a herramienta: Si es necesario, el agente invoca una o varias herramientas.
- Observación: El agente recibe los resultados de las herramientas.
- Decisión: El agente decide si continúa (vuelve al paso 2) o responde.
- Respuesta: El agente genera su respuesta final.
La clave reside en el bucle entre los pasos 2 y 5, que puede ejecutarse varias veces. Un agente puede encadenar 5, 10 o incluso 20 llamadas a herramientas antes de producir una respuesta final, sin que tengas que escribir ni una línea de código de orquestación. El ejemplo siguiente ilustra esto: se declaran dos herramientas independientes y el modelo decide cómo encadenarlas.
from agents import Agent, Runner, function_tool
@function_tool
def rechercher_produit(nom: str) -> str:
"""Busca un producto en el catálogo."""
# Simulación: en producción, llama a tu base de datos
catalogue = {
"laptop-pro": {"prix": 1299, "stock": 45},
"tablet-air": {"prix": 599, "stock": 120},
}
produit = catalogue.get(nom)
if produit:
return f"Produit {nom}: {produit['prix']}€, stock: {produit['stock']}"
return f"Produit {nom} non trouvé"
@function_tool
def calculer_remise(prix: float, pourcentage: float) -> str:
"""Calcula el precio tras aplicar el descuento."""
prix_final = prix * (1 - pourcentage / 100)
return f"Prix après {pourcentage}% de remise : {prix_final:.2f}€"
agent = Agent(
name="Sales Agent",
instructions="Ayudas a los clientes a encontrar productos y calcular descuentos.",
tools=[rechercher_produit, calculer_remise],
model="gpt-5.6-terra",
)
# El agente hará lo siguiente: 1) buscar el producto, 2) calcular el descuento, 3) responder
result = Runner.run_sync(
agent,
"What is the price of the laptop-pro with a 15% discount?"
)
print(result.final_output)
La pregunta requiere dos operaciones que no están explícitamente vinculadas en el código. El agente realiza automáticamente dos llamadas a herramientas en secuencia: primero rechercher_produit y luego calculer_remise con el precio recuperado. Este encadenamiento es una decisión del modelo, no una instrucción tuya.
Estructura interna: elementos y mensajes
La API de Responses estructura cada interacción como elementos (items). Al leerlos, puedes ver qué ha hecho realmente tu agente. En la conversación aparecen tres tipos:
message: un mensaje de texto (del usuario o del agente).function_call: una llamada a herramienta decidida por el agente.function_call_output: el resultado devuelto por la herramienta.
result = Runner.run_sync(agent, "Find the tablet-air")
# Inspecciona los pasos de razonamiento
for item in result.raw_responses:
print(f"Type: {type(item).__name__}")
# Verás: message input → function_call → function_call_output → message output
Acostúmbrate a rastrear este bucle siempre que un agente genere una respuesta sorprendente. Nueve de cada diez veces, la anomalía aparece en una function_call con argumentos inesperados.
Llamadas paralelas frente a secuenciales
No todos los pasos dependen unos de otros. Cuando dos llamadas son independientes, el agente puede decidir ejecutarlas en paralelo.
@function_tool
def obtenir_meteo(ville: str) -> str:
"""Obtiene el tiempo actual de una ciudad."""
meteos = {"Paris": "18°C, sunny", "Lyon": "16°C, cloudy"}
return meteos.get(ville, "Data unavailable")
agent = Agent(
name="Travel Agent",
instructions="Ayudas a planificar viajes.",
tools=[obtenir_meteo, rechercher_produit],
model="gpt-5.6-terra",
)
# El agente llamará a obtenir_meteo("Paris") y obtenir_meteo("Lyon") en paralelo
result = Runner.run_sync(
agent,
"What's the weather in Paris and Lyon?"
)
El tiempo en Lyon no depende del de París: el SDK gestiona el paralelismo automáticamente y lanza ambas llamadas simultáneamente, reduciendo la latencia. Compáralo con el ejemplo de ventas anterior, donde el cálculo del descuento tenía que esperar al precio: en ese caso, la secuencia se impone por sí sola.
El parámetro max_turns
Un bucle autónomo puede, en el peor de los casos, no detenerse nunca: el agente llama a una herramienta, el resultado le lleva a llamar a otra, y así sucesivamente. La salvaguarda es un único parámetro.
result = Runner.run_sync(
agent,
"Full catalog analysis",
max_turns=10 # Máximo 10 iteraciones del bucle
)
Si el agente alcanza el límite, se detiene con los resultados obtenidos hasta ese momento. En producción, esto es una medida de seguridad esencial: limita tanto el tiempo de respuesta como el coste.
Puntos clave
- Un agente se ejecuta en un bucle: razonamiento → herramienta → observación → decisión.
- Este bucle puede ejecutarse varias veces antes de producir una respuesta.
- El modelo decide automáticamente qué herramientas llamar y en qué orden.
- Las llamadas a herramientas independientes se ejecutan en paralelo.
max_turnslimita el número de iteraciones por seguridad.