Llamada de función

Utilice Llamadas de función para permitir que el modelo solicite datos o acciones de la aplicación durante un flujo de trabajo de API de respuestas. Esto resulta útil cuando el modelo necesita información u operaciones que no están disponibles en la petición de datos en sí, como datos de calendario, estado interno de la aplicación o el resultado de una operación personalizada.

Con este patrón, el modelo no ejecuta la función directamente. En su lugar, devuelve el nombre y los argumentos de la función, la aplicación ejecuta la función y, a continuación, la aplicación vuelve a enviar la salida de la función para que el modelo pueda continuar y producir la respuesta orientada al usuario.

Lo que esto permite

Las llamadas de función son útiles cuando la aplicación necesita mantener el control de la ejecución y, al mismo tiempo, permitir que el modelo decida cuándo se necesita información externa.

Ejemplos de casos de uso

Consulta de eventos de calendario
Recuperando datos de aplicación
Llamada a API interna o externa
Ejecución de cálculos o lógica de negocio

En la función, puede llamar a un servicio externo, una base de datos, una de sus propias API de biblioteca, una CLI o un servidor MCP local.

Este enfoque proporciona flexibilidad a la vez que mantiene la ruta de ejecución dentro de la aplicación.

Flujo de ejecución

Una función típica que llama a la interacción funciona de la siguiente manera:

El cliente envía una solicitud que incluye una o más definiciones de herramientas de funciones.
El modelo decide si una de esas herramientas es necesaria.
Si se necesita una herramienta, el modelo devuelve el nombre de la función y los argumentos.
La aplicación ejecuta la función y prepara el resultado.
La aplicación envía ese resultado de nuevo en una solicitud de seguimiento.
El modelo utiliza ese resultado para completar la respuesta.

Opciones de manejo de estado

Existen dos formas comunes de gestionar el estado en estas solicitudes:

Estado gestionado por el servicio

Recomendado para la mayoría de los casos de uso. La solicitud de seguimiento incluye previous_response_id y el servicio realiza un seguimiento del intercambio anterior.
Estado gestionado por el cliente

La aplicación mantiene el historial completo de interacciones y envía el contexto acumulado con cada solicitud.

Consejo

Mantenga las definiciones de herramientas precisas. Los nombres claros, las descripciones bien escritas y los parámetros bien definidos ayudan al modelo a seleccionar la herramienta adecuada y generar argumentos utilizables.

Definición de una herramienta de función

Para definir una herramienta de función, agregue una entrada en la propiedad tools con "type": "function".

En el siguiente ejemplo, se define una herramienta que recupera eventos de calendario para una fecha especificada:

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

Incluya esta matriz tools en la solicitud client.responses.create().

Ejemplo: Estado Gestionado por Servicio

En este patrón, la primera solicitud permite al modelo decidir si la herramienta es necesaria. La segunda solicitud devuelve el resultado de la herramienta y hace referencia a la respuesta anterior.

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

# Initial request
response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input="Show the calendar events for 2026-04-02.",
)

# Execute the requested function
tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        tool_outputs.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

# Follow-up request
final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=tool_outputs,
    previous_response_id=response.id,
)

print(final.output_text)

Ejemplo: estado gestionado por el cliente

En este patrón, la aplicación mantiene el intercambio completo y lo vuelve a enviar con la solicitud de seguimiento.

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

conversation = [
    {"role": "user", "content": "Show the calendar events for 2026-04-02."}
]

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input=conversation,
)

conversation += response.output

for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        conversation.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=conversation,
)

print(final.output_text)

La llamada a funciones es una opción sólida cuando la aplicación debe seguir siendo responsable de la ejecución, el control de acceso y la lógica de integración, al tiempo que permite al modelo solicitar la información que necesita.