Use la herramienta de funciones

La herramienta de función permite al modelo llamar a funciones definidas por el desarrollador para recuperar datos o desencadenar acciones durante una respuesta.

¿Cuál es la función de la herramienta?

La herramienta de funciones (llamada a funciones) permite a un modelo decidir cuándo invocar herramientas designadas que expone en la aplicación. El modelo no ejecuta la lógica de negocios directamente. En su lugar, devuelve una llamada de función estructurada, el código ejecuta la función y, a continuación, pasa la salida de la función al modelo.

Este patrón es ideal para conectar el razonamiento del modelo a sistemas reales, como API, bases de datos, flujos de trabajo empresariales y funciones de utilidad.

Entre las características clave se incluyen:

• Llamadas a herramientas estructuradas : el modelo emite solicitudes explícitas de llamada de función.
• Ejecución controlada por desarrolladores : la aplicación decide cómo y dónde se ejecutan las funciones
• Patrón de integración confiable : llamadas a API, servicios internos o utilidades auxiliares de forma segura
• Orquestación multiturno: devuelve la resultado de la herramienta y permite que el modelo siga con el proceso de razonamiento
• Respuestas fundamentadas: pueden incluir datos en tiempo real generados por el sistema

Casos de uso comunes

Un ejemplo sencillo

Este es un ejemplo que expone una get_time función y permite que el modelo lo llame cuando sea necesario:

import time
from openai import OpenAI

# Function to get the current time
def get_time():
    return f"The time is {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime())}"


# Main function
def main():
    client = OpenAI(
        base_url={openai_endpoint},
        api_key={auth_key_or_token}
    )

    function_tools = [
        {
            "type": "function",
            "name": "get_time",
            "description": "Get the current time"
        }
    ]

    # Initialize messages with a system prompt
    messages = [
        {"role": "developer", "content": "You are an AI assistant that provides information."},
    ]

    # Loop until the user types 'quit'
    while True:
        prompt = input("\nEnter a prompt (or type 'quit' to exit)\n")
        if prompt.lower() == "quit":
            break

        # Append the user prompt to the messages
        messages.append({"role": "user", "content": prompt})

        # Get initial response
        response = client.responses.create(
            model=model_deployment,
            input=messages,
            tools=function_tools
        )

        # Append model output to the messages
        messages += response.output

        # Was there a function call?
        for item in response.output:
            if item.type == "function_call" and item.name == "get_time":
                current_time = get_time()
                messages.append({
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": current_time
                })

                # Get a follow up response using the tool output
                response = client.responses.create(
                    model=model_deployment,
                    instructions="Answer only with the tool output.",
                    input=messages,
                    tools=function_tools
                )

        print(response.output_text)


# Run the main function when the script starts
if __name__ == '__main__':
    main()

En este flujo, el modelo decide cuándo llamar a get_time, el código ejecuta la función y luego el modelo devuelve una respuesta final fundamentada. Dado que el usuario puede escribir cualquier comando, el modelo debe determinar cuándo necesita ejecutar la función. Si lo hace, la respuesta al aviso incluirá una llamada a función, que el código de la aplicación debe implementar antes de enviar un nuevo aviso con la salida de la función para que el modelo procese.

La salida podría tener un aspecto similar al siguiente:

Enter a prompt (or type 'quit' to exit)
Hello

Hello! How can I help you today?

Enter a prompt (or type 'quit' to exit)
What time is it?

The time is 2026-03-19 17:17:41.

Enter a prompt (or type 'quit' to exit)

El primer mensaje de usuario ("Hello") no requería el uso de la herramienta de función, por lo que el modelo respondió con normalidad. El segundo aviso ("¿Qué hora es?") desencadenó el modelo para seleccionar la get_time función, que indica en su respuesta. A continuación, el código de la aplicación ejecutó la función y devolvió los resultados al modelo, que luego envió una segunda respuesta con los resultados de la función.

Funcionamiento de la herramienta funcional

El proceso general para usar la herramienta de función es:

1. Define las herramientas - Proporcione una o varias definiciones de función en el array de herramientas.
2. El modelo evalúa el prompt - Determina si se necesita una llamada de función.
3. El modelo emite una llamada de función : la respuesta incluye el nombre de la función y los metadatos de llamada.
4. La aplicación ejecuta lógica: ejecute la función coincidente en el código.
5. Devuelve el resultado de la función: envíe un elemento function_call_output con el resultado.
6. El modelo completa la respuesta : incorpora los resultados de la herramienta en la respuesta final.

procedimientos recomendados

• Mantener las herramientas centradas : las funciones pequeñas y de un solo propósito son más fáciles de controlar y probar
• Validar entradas de función - Nunca confiar ciegamente en los argumentos de las herramientas en sistemas de producción
• Control de errores de forma segura : devuelve salidas de error claras sobre las que el modelo puede razonar
• Uso de la herramienta de registro : seguimiento de las llamadas, la latencia y las tasas de error para la depuración y la gobernanza
• Limitar las operaciones confidenciales : requerir autorización explícita para acciones de alto impacto

Limitaciones sobre las que conocer

• El modelo solicita llamadas de función, pero la aplicación debe ejecutarlas.
• Se pueden producir argumentos de herramienta incorrectos o inesperados y deben validarse.
• La latencia de las herramientas puede aumentar el tiempo de respuesta de un extremo a otro
• La llamada a funciones mejora la confiabilidad, pero las salidas finales siguen necesitando revisión para las decisiones críticas.

Si se utiliza correctamente, la herramienta de funciones convierte un modelo de un generador de texto en un orquestador que puede interactuar con sistemas reales de una manera controlada y auditable.