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

Arquitectura de llamada a funciones en la API de Respuestas

Lección 1 de 20 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Arquitectura de llamada a funciones en la API de Respuestas
  2. El principio fundamental
  3. Anatomía de una respuesta
  4. El bucle completo
  5. Diferencias clave respecto a Chat Completions
  6. ¿Cuándo llama el modelo a una función?
  7. Puntos clave

Actualizado el 2 de noviembre de 2026 según la documentación de OpenAI: la herramienta Code Interpreter requiere ahora un parámetro container (añadido a todos los ejemplos), las partes de texto de entrada utilizan el tipo input_text y la búsqueda web emplea la herramienta web_search (web_search_preview es ahora una herramienta heredada sin filtros de dominio). Los archivos generados se recuperan mediante las funciones fichiers_generes y telecharger de la Lección 10. Fuentes: Code Interpreter · Búsqueda web.

Arquitectura de llamada a funciones en la API de Respuestas

La llamada a funciones es el mecanismo central que permite a los modelos de OpenAI interactuar con el mundo exterior. En la API de Respuestas, este mecanismo se ha rediseñado para ser más robusto, predecible y estar integrado de forma nativa con herramientas incorporadas como Búsqueda Web y Code Interpreter.

El principio fundamental

El modelo nunca realiza ninguna acción directamente. Emite intenciones estructuradas que tu código intercepta y ejecuta. Dicho así, podría parecer una limitación técnica; en realidad, es la decisión de diseño que hace posible todo lo demás.

Considera la alternativa. Si el modelo ejecutara las acciones por sí mismo, tendrías que entregarle las credenciales de tu base de datos, claves de API y permisos de escritura, y no tendrías ningún punto en el que verificar nada. Con el desacoplamiento, cada intención pasa por tu código: validas los argumentos, aplicas las reglas de negocio y rechazas la operación si es necesario. El modelo propone, tu código dispone, y ese límite es lo que te permite poner la llamada a funciones en producción sin perder el control.

from openai import OpenAI

client = OpenAI()

# Declarar una herramienta personalizada
tools = [{
    "type": "function",
    "name": "rechercher_client",
    "description": "Buscar un cliente en el CRM por nombre o correo electrónico",
    "parameters": {
        "type": "object",
        "properties": {
            "terme": {
                "type": "string",
                "description": "Nombre, correo electrónico o ID del cliente"
            },
            "champ": {
                "type": "string",
                "enum": ["nom", "email", "id"],
                "description": "Campo en el que buscar"
            }
        },
        "required": ["terme"]
    }
}]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Encuentra al cliente Jean Dupont",
    tools=tools
)

Anatomía de una respuesta

Una respuesta no contiene o bien texto o bien llamadas a herramientas: output es una lista heterogénea que puede mezclar ambas cosas. El hábito que debes adquirir desde tu primera línea de código es iterar sobre esta lista en lugar de leer output[0]. Un modelo que explica su razonamiento antes de llamar a una función produce exactamente ese caso, y un código que lee el primer elemento fallará el día que empiece a añadir comentarios.

for item in response.output:
    if item.type == "function_call":
        print(f"ID llamada  : {item.call_id}")
        print(f"Función     : {item.name}")
        print(f"Argumentos  : {item.arguments}")

El call_id es esencial: vincula la llamada con su resultado cuando envías la respuesta de vuelta al modelo. En una única llamada apenas se nota; en tres llamadas paralelas, es lo único que evita que atribuyas el tiempo de Lyon a la solicitud sobre Marsella. Devuelve siempre el resultado con el call_id que recibiste, nunca con un ID que reconstruyas por tu cuenta.

El bucle completo

Este ciclo de cuatro pasos es invariable: se cumple tanto para una función como para veinte, para una llamada simple o para un agente que encadena diez herramientas. Toda la complejidad que encontrarás más adelante —paralelismo, errores, alternativas— consiste en instrumentar este bucle, nunca en reemplazarlo.

import json

# 1. Primera llamada con herramientas declaradas
response = client.responses.create(
    model="gpt-5.6-terra",
    input="¿Cuál es el saldo del cliente [email protected]?",
    tools=tools
)

# 2. Detectar y ejecutar llamadas a funciones
resultats = []
for item in response.output:
    if item.type == "function_call":
        if item.name == "rechercher_client":
            args = json.loads(item.arguments)
            resultat = votre_crm.rechercher(args["terme"])
            resultats.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(resultat)
            })

# 3. Enviar los resultados de vuelta al modelo
response_finale = client.responses.create(
    model="gpt-5.6-terra",
    input=response.output + resultats,
    tools=tools
)

# 4. El modelo formula su respuesta natural
print(response_finale.output_text)

Diferencias clave respecto a Chat Completions

La API de Respuestas aporta varias mejoras arquitectónicas.

Gestión nativa de herramientas incorporadas

Las herramientas incorporadas se declaran exactamente igual que tus funciones, pero se ejecutan del lado de OpenAI. La consecuencia práctica es agradable: no escribes ningún bucle para ellas. El modelo llama, obtiene el resultado y continúa, todo en una única ida y vuelta. El bucle descrito anteriormente solo afecta a tus funciones, las que se ejecutan en tu máquina.

# Mezclar herramientas incorporadas y personalizadas
tools = [
    {"type": "web_search"},
    {"type": "code_interpreter", "container": {"type": "auto"}},
    {
        "type": "function",
        "name": "ma_fonction",
        "description": "Mi función personalizada",
        "parameters": {"type": "object", "properties": {}}
    }
]

Identificadores de llamada estables

Cada llamada a función recibe un call_id único que te permite rastrear con precisión qué resultado corresponde a qué llamada, incluso con llamadas paralelas.

Flujo simplificado

No es necesario gestionar manualmente los roles assistant y tool en los mensajes. El campo input acepta directamente concatenar salidas anteriores con resultados de funciones.

¿Cuándo llama el modelo a una función?

El modelo decide llamar a una función cuando la solicitud del usuario requiere información de la que no dispone, cuando la descripción de la función coincide con la necesidad identificada y cuando los parámetros requeridos pueden inferirse del contexto.

Por tanto, deben cumplirse simultáneamente tres condiciones, y eso es útil para la depuración: cuando una función no se llama aunque debería hacerlo, la causa es casi siempre la segunda: una descripción que no cubre la forma en que el usuario ha formulado su solicitud. El parámetro tool_choice te permite forzar el comportamiento cuando la descripción no es suficiente:

# Dejar que el modelo decida
tool_choice = "auto"

# Forzar una llamada a una función específica
tool_choice = {"type": "function", "name": "rechercher_client"}

# Prohibir todas las llamadas a funciones
tool_choice = "none"

# Exigir al menos una llamada sin especificar cuál
tool_choice = "required"

Puntos clave

  • La llamada a funciones es un protocolo de intenciones, no un protocolo de ejecución
  • El bucle llamar-ejecutar-devolver es el patrón fundamental
  • Las herramientas incorporadas y personalizadas coexisten en el mismo array tools
  • call_id garantiza la trazabilidad de cada llamada
  • tool_choice te permite controlar con precisión el comportamiento del modelo