Ir al contenido principal
Español— Elegir un idioma
Menú

Arquitectura de agente: el bucle de razonamiento y herramientas

Lección 2 de 25 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Arquitectura de agente: el bucle de razonamiento y herramientas
  2. El ciclo de vida del agente
  3. Estructura interna: elementos y mensajes
  4. Llamadas paralelas frente a secuenciales
  5. El parámetro max_turns
  6. Puntos clave

Actualizado el 3 de noviembre de 2026: En rechercher_produit, faltaban las comillas en las claves prix y stock, lo que provocaba un NameError en 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:

  1. Recepción: El agente recibe el mensaje del usuario y las instrucciones del sistema.
  2. Razonamiento: El modelo analiza la solicitud y decide la siguiente acción.
  3. Llamada a herramienta: Si es necesario, el agente invoca una o varias herramientas.
  4. Observación: El agente recibe los resultados de las herramientas.
  5. Decisión: El agente decide si continúa (vuelve al paso 2) o responde.
  6. 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_turns limita el número de iteraciones por seguridad.