Cómo usar la llamada a funciones con Azure OpenAI en Microsoft Foundry Models

Si se incluyen una o varias funciones en tu solicitud, el modelo determina si alguna de las funciones debería llamarse según el contexto del prompt. Cuando el modelo determina que se debe llamar a una función, responde con un objeto JSON, incluidos los argumentos de la función.

Los modelos formulan llamadas API y salidas de datos de estructura, todas basadas en las funciones que especifique. Es importante tener en cuenta que, aunque los modelos pueden generar estas llamadas, es necesario ejecutarlas, asegurándose de mantener el control.

A grandes rasgos, puede desglosar el trabajo con funciones en tres pasos:

  1. Llame a la API de completadores de chat usando sus funciones y la entrada del usuario.
  2. Utilizar la respuesta del modelo para invocar tu API o función.
  3. Vuelva a llamar a la API de completaciones de chat, incluyendo la respuesta de tu función para obtener una respuesta final.

Requisitos previos

  • Un modelo de OpenAI Azure implementado
  • Para la autenticación de Microsoft Entra ID:

Ejemplo de llamada a una sola herramienta o función

En primer lugar, se muestra una llamada a función toy que puede comprobar la hora en tres ubicaciones codificadas de forma codificada con una sola herramienta o función definida. Hemos agregado instrucciones de impresión para ayudar a que la ejecución del código sea más fácil de seguir:

import os
import json
from openai import OpenAI
from datetime import datetime
from zoneinfo import ZoneInfo
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

# Define the deployment you want to use for your chat completions API calls

deployment_name = "<YOUR_DEPLOYMENT_NAME_HERE>"

# Simplified timezone data
TIMEZONE_DATA = {
    "tokyo": "Asia/Tokyo",
    "san francisco": "America/Los_Angeles",
    "paris": "Europe/Paris"
}

def get_current_time(location):
    """Get the current time for a given location"""
    print(f"get_current_time called with location: {location}")  
    location_lower = location.lower()
    
    for key, timezone in TIMEZONE_DATA.items():
        if key in location_lower:
            print(f"Timezone found for {key}")  
            current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
            return json.dumps({
                "location": location,
                "current_time": current_time
            })
    
    print(f"No timezone data found for {location_lower}")  
    return json.dumps({"location": location, "current_time": "unknown"})

def run_conversation():
    # Initial user message
    messages = [{"role": "user", "content": "What's the current time in San Francisco"}] # Single function call
    #messages = [{"role": "user", "content": "What's the current time in San Francisco, Tokyo, and Paris?"}] # Parallel function call with a single tool/function defined

    # Define the function for the model
    tools = [
        {
            "type": "function",
            "function": {
                "name": "get_current_time",
                "description": "Get the current time in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city name, e.g. San Francisco",
                        },
                    },
                    "required": ["location"],
                },
            }
        }
    ]

    # First API call: Ask the model to use the function
    response = client.chat.completions.create(
        model=deployment_name,
        messages=messages,
        tools=tools,
        tool_choice="auto",
    )

    # Process the model's response
    response_message = response.choices[0].message
    messages.append(response_message)

    print("Model's response:")  
    print(response_message)  

    # Handle function calls
    if response_message.tool_calls:
        for tool_call in response_message.tool_calls:
            if tool_call.function.name == "get_current_time":
                function_args = json.loads(tool_call.function.arguments)
                print(f"Function arguments: {function_args}")  
                time_response = get_current_time(
                    location=function_args.get("location")
                )
                messages.append({
                    "tool_call_id": tool_call.id,
                    "role": "tool",
                    "name": "get_current_time",
                    "content": time_response,
                })
    else:
        print("No tool calls were made by the model.")  

    # Second API call: Get the final response from the model
    final_response = client.chat.completions.create(
        model=deployment_name,
        messages=messages,
    )

    return final_response.choices[0].message.content

# Run the conversation and print the result
print(run_conversation())

Salida:

Model's response:
ChatCompletionMessage(content=None, role='assistant', function_call=None, tool_calls=[ChatCompletionMessageToolCall(id='call_pOsKdUlqvdyttYB67MOj434b', function=Function(arguments='{"location":"San Francisco"}', name='get_current_time'), type='function')])
Function arguments: {'location': 'San Francisco'}
get_current_time called with location: San Francisco
Timezone found for san francisco
The current time in San Francisco is 09:24 AM.

Si usamos una implementación de modelo que admite llamadas de función paralelas, podríamos convertirla en un ejemplo de llamada de función paralela cambiando la matriz de mensajes para solicitar la hora en varias ubicaciones en lugar de una.

Para lograr esto, intercambie los comentarios de estas dos líneas:

    messages = [{"role": "user", "content": "What's the current time in San Francisco"}] # Single function call
    #messages = [{"role": "user", "content": "What's the current time in San Francisco, Tokyo, and Paris?"}] # Parallel function call with a single tool/function defined

Para que se vea así y vuelva a ejecutar el código:

    #messages = [{"role": "user", "content": "What's the current time in San Francisco"}] # Single function call
    messages = [{"role": "user", "content": "What's the current time in San Francisco, Tokyo, and Paris?"}] # Parallel function call with a single tool/function defined

Esto genera la siguiente salida:

Salida:

Model's response:
ChatCompletionMessage(content=None, role='assistant', function_call=None, tool_calls=[ChatCompletionMessageToolCall(id='call_IjcAVz9JOv5BXwUx1jd076C1', function=Function(arguments='{"location": "San Francisco"}', name='get_current_time'), type='function'), ChatCompletionMessageToolCall(id='call_XIPQYTCtKIaNCCPTdvwjkaSN', function=Function(arguments='{"location": "Tokyo"}', name='get_current_time'), type='function'), ChatCompletionMessageToolCall(id='call_OHIB5aJzO8HGqanmsdzfytvp', function=Function(arguments='{"location": "Paris"}', name='get_current_time'), type='function')])
Function arguments: {'location': 'San Francisco'}
get_current_time called with location: San Francisco
Timezone found for san francisco
Function arguments: {'location': 'Tokyo'}
get_current_time called with location: Tokyo
Timezone found for tokyo
Function arguments: {'location': 'Paris'}
get_current_time called with location: Paris
Timezone found for paris
As of now, the current times are:

- **San Francisco:** 11:15 AM
- **Tokyo:** 03:15 AM (next day)
- **Paris:** 08:15 PM

Las llamadas a funciones paralelas permiten realizar varias llamadas de función juntas, lo que permite la ejecución en paralelo y la recuperación de resultados. Esto reduce el número de llamadas a la API que se deben realizar y puede mejorar el rendimiento general.

Por ejemplo, en nuestra sencilla aplicación de tiempo, recuperamos múltiples registros temporales al mismo tiempo. Esto dio lugar a un mensaje de finalización del chat con tres llamadas de función en la tool_calls matriz, cada una con un único id. Si quisieras responder a estas llamadas de función, añadirías tres nuevos mensajes a la conversación, cada uno conteniendo el resultado de una llamada de función, con un tool_call_id que hace referencia desde id a tool_calls.

Para forzar que el modelo llame a una función específica, establezca en tool_choice un objeto de herramienta con nombre, por ejemplo: tool_choice={"type": "function", "function": {"name": "get_current_time"}}. Para forzar un mensaje orientado al usuario, establezca tool_choice="none".

Nota

El comportamiento predeterminado (tool_choice: "auto") es para que el modelo decida por sí mismo si debe llamar a una función y, si es así, qué función llamar.

Ejecución paralela de múltiples funciones

Ahora demostramos otro ejemplo de llamada a una función de juguete, esta vez con dos funciones diferentes definidas.

import os
import json
from openai import OpenAI
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

# Provide the model deployment name you want to use for this example

deployment_name = "YOUR_DEPLOYMENT_NAME_HERE" 

# Simplified weather data
WEATHER_DATA = {
    "tokyo": {"temperature": "10", "unit": "celsius"},
    "san francisco": {"temperature": "72", "unit": "fahrenheit"},
    "paris": {"temperature": "22", "unit": "celsius"}
}

# Simplified timezone data
TIMEZONE_DATA = {
    "tokyo": "Asia/Tokyo",
    "san francisco": "America/Los_Angeles",
    "paris": "Europe/Paris"
}

def get_current_weather(location, unit=None):
    """Get the current weather for a given location"""
    location_lower = location.lower()
    print(f"get_current_weather called with location: {location}, unit: {unit}")  
    
    for key in WEATHER_DATA:
        if key in location_lower:
            print(f"Weather data found for {key}")  
            weather = WEATHER_DATA[key]
            return json.dumps({
                "location": location,
                "temperature": weather["temperature"],
                "unit": unit if unit else weather["unit"]
            })
    
    print(f"No weather data found for {location_lower}")  
    return json.dumps({"location": location, "temperature": "unknown"})

def get_current_time(location):
    """Get the current time for a given location"""
    print(f"get_current_time called with location: {location}")  
    location_lower = location.lower()
    
    for key, timezone in TIMEZONE_DATA.items():
        if key in location_lower:
            print(f"Timezone found for {key}")  
            current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
            return json.dumps({
                "location": location,
                "current_time": current_time
            })
    
    print(f"No timezone data found for {location_lower}")  
    return json.dumps({"location": location, "current_time": "unknown"})

def run_conversation():
    # Initial user message
    messages = [{"role": "user", "content": "What's the weather and current time in San Francisco, Tokyo, and Paris?"}]

    # Define the functions for the model
    tools = [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city name, e.g. San Francisco",
                        },
                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                    },
                    "required": ["location"],
                },
            }
        },
        {
            "type": "function",
            "function": {
                "name": "get_current_time",
                "description": "Get the current time in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city name, e.g. San Francisco",
                        },
                    },
                    "required": ["location"],
                },
            }
        }
    ]

    # First API call: Ask the model to use the functions
    response = client.chat.completions.create(
        model=deployment_name,
        messages=messages,
        tools=tools,
        tool_choice="auto",
    )

    # Process the model's response
    response_message = response.choices[0].message
    messages.append(response_message)

    print("Model's response:")  
    print(response_message)  

    # Handle function calls
    if response_message.tool_calls:
        for tool_call in response_message.tool_calls:
            function_name = tool_call.function.name
            function_args = json.loads(tool_call.function.arguments)
            print(f"Function call: {function_name}")  
            print(f"Function arguments: {function_args}")  
            
            if function_name == "get_current_weather":
                function_response = get_current_weather(
                    location=function_args.get("location"),
                    unit=function_args.get("unit")
                )
            elif function_name == "get_current_time":
                function_response = get_current_time(
                    location=function_args.get("location")
                )
            else:
                function_response = json.dumps({"error": "Unknown function"})
            
            messages.append({
                "tool_call_id": tool_call.id,
                "role": "tool",
                "name": function_name,
                "content": function_response,
            })
    else:
        print("No tool calls were made by the model.")  

    # Second API call: Get the final response from the model
    final_response = client.chat.completions.create(
        model=deployment_name,
        messages=messages,
    )

    return final_response.choices[0].message.content

# Run the conversation and print the result
print(run_conversation())

Salida

Model's response:
ChatCompletionMessage(content=None, role='assistant', function_call=None, tool_calls=[ChatCompletionMessageToolCall(id='call_djHAeQP0DFEVZ2qptrO0CYC4', function=Function(arguments='{"location": "San Francisco", "unit": "celsius"}', name='get_current_weather'), type='function'), ChatCompletionMessageToolCall(id='call_q2f1HPKKUUj81yUa3ITLOZFs', function=Function(arguments='{"location": "Tokyo", "unit": "celsius"}', name='get_current_weather'), type='function'), ChatCompletionMessageToolCall(id='call_6TEY5Imtr17PaB4UhWDaPxiX', function=Function(arguments='{"location": "Paris", "unit": "celsius"}', name='get_current_weather'), type='function'), ChatCompletionMessageToolCall(id='call_vpzJ3jElpKZXA9abdbVMoauu', function=Function(arguments='{"location": "San Francisco"}', name='get_current_time'), type='function'), ChatCompletionMessageToolCall(id='call_1ag0MCIsEjlwbpAqIXJbZcQj', function=Function(arguments='{"location": "Tokyo"}', name='get_current_time'), type='function'), ChatCompletionMessageToolCall(id='call_ukOu3kfYOZR8lpxGRpdkhhdD', function=Function(arguments='{"location": "Paris"}', name='get_current_time'), type='function')])
Function call: get_current_weather
Function arguments: {'location': 'San Francisco', 'unit': 'celsius'}
get_current_weather called with location: San Francisco, unit: celsius
Weather data found for san francisco
Function call: get_current_weather
Function arguments: {'location': 'Tokyo', 'unit': 'celsius'}
get_current_weather called with location: Tokyo, unit: celsius
Weather data found for tokyo
Function call: get_current_weather
Function arguments: {'location': 'Paris', 'unit': 'celsius'}
get_current_weather called with location: Paris, unit: celsius
Weather data found for paris
Function call: get_current_time
Function arguments: {'location': 'San Francisco'}
get_current_time called with location: San Francisco
Timezone found for san francisco
Function call: get_current_time
Function arguments: {'location': 'Tokyo'}
get_current_time called with location: Tokyo
Timezone found for tokyo
Function call: get_current_time
Function arguments: {'location': 'Paris'}
get_current_time called with location: Paris
Timezone found for paris
Here's the current information for the three cities:

### San Francisco
- **Time:** 09:13 AM
- **Weather:** 72°C (quite warm!)

### Tokyo
- **Time:** 01:13 AM (next day)
- **Weather:** 10°C

### Paris
- **Time:** 06:13 PM
- **Weather:** 22°C

Is there anything else you need?

Importante

Es posible que la respuesta JSON no siempre sea válida, por lo que debe agregar lógica adicional al código para poder controlar los errores. En algunos casos de uso, es posible que tenga que utilizar el ajuste fino para mejorar el rendimiento de las llamadas de funciones.

Ingeniería de mensajes con funciones

Al definir una función como parte de la solicitud, los detalles se insertan en el mensaje del sistema mediante una sintaxis específica en la que se ha entrenado el modelo. Esto significa que las funciones consumen tokens en el indicador y que puede aplicar técnicas de ingeniería de indicaciones para optimizar el rendimiento de las llamadas de función. El modelo utiliza el contexto completo de la indicación para determinar si se debe llamar a una función, incluida la definición de función, el mensaje del sistema y los mensajes del usuario.

Mejora de la calidad y confiabilidad

Si el modelo no está llamando a la función cuando, o cómo, usted espera, hay algunas cosas que puede intentar hacer para mejorar la calidad.

Proporcione más detalles en la definición de la función.

Es importante proporcionar un significado description de la función y proporcionar descripciones para cualquier parámetro que pueda no ser obvio para el modelo. Por ejemplo, en la descripción del location parámetro , puede incluir detalles adicionales y ejemplos en el formato de la ubicación.

"location": {
    "type": "string",
    "description": "The location of the hotel. The location should include the city and the state's abbreviation (i.e. Seattle, WA or Miami, FL)"
},
Proporcionar más contexto en el mensaje del sistema

El mensaje del sistema también se puede usar para proporcionar más contexto al modelo. Por ejemplo, si tiene una función denominada search_hotels podría incluir un mensaje del sistema como el siguiente para indicar al modelo que llame a la función cuando un usuario solicite ayuda para encontrar un hotel.

{"role": "system", "content": "You're an AI assistant designed to help users search for hotels. When a user asks for help finding a hotel, you should call the search_hotels function."}
Indique al modelo que haga preguntas aclarando

En algunos casos, desea indicar al modelo que haga preguntas aclaradas para evitar realizar suposiciones sobre qué valores usar con funciones. Por ejemplo, con search_hotels, querrías que el modelo solicitara aclaraciones si la solicitud del usuario no incluye detalles sobre location. Para indicar al modelo que haga una pregunta aclarada, podría incluir contenido como el ejemplo siguiente en el mensaje del sistema.

{"role": "system", "content": "Don't make assumptions about what values to use with functions. Ask for clarification if a user request is ambiguous."}

Reducción de errores

Otro área en la que la ingeniería de avisos puede ser valiosa es reducir los errores en las llamadas de función. Los modelos se entrenan para generar llamadas de función que coincidan con el esquema que defina, pero los modelos generan una llamada de función que no coincide con el esquema definido o intentan llamar a una función que no incluyó.

Si encuentra que el modelo está generando llamadas de función que no se proporcionaron, intente incluir una oración en el mensaje del sistema que indica "Only use the functions you have been provided with.".

Uso de la llamada de función de forma responsable

Al igual que cualquier sistema de inteligencia artificial, el uso de llamadas a funciones para integrar modelos de lenguaje con otras herramientas y sistemas presenta posibles riesgos. Es importante comprender los riesgos que podrían presentar las llamadas a funciones y tomar medidas para asegurarse de que usa las funcionalidades de forma responsable.

Estas son algunas sugerencias para ayudarle a usar funciones de forma segura y segura:

  • Validar llamadas de función: compruebe siempre las llamadas de función generadas por el modelo. Esto incluye comprobar los parámetros, la función a la que se llama y asegurarse de que la llamada se alinea con la acción prevista.
  • Usar herramientas y datos de confianza: use solo datos de orígenes de confianza y comprobados. Los datos que no son de confianza en la salida de una función se pueden usar para indicar al modelo que escriba llamadas de función de una manera distinta de la prevista.
  • Siga el principio de privilegios mínimos: conceda solo el acceso mínimo necesario para que la función realice su trabajo. Esto reduce el impacto potencial si una función se utiliza incorrectamente o se explota. Por ejemplo, si usa llamadas de función para consultar una base de datos, solo debe conceder a la aplicación acceso de solo lectura a la base de datos. Tampoco debe depender únicamente de la exclusión de capacidades en la definición de funciones como medida de control de seguridad.
  • Considere el Impacto en el Mundo Real: tenga en cuenta el impacto real de las invocaciones a funciones que planea ejecutar, especialmente aquellas que provocan acciones como ejecutar código, actualizar bases de datos o enviar notificaciones.
  • Implementar pasos de confirmación de usuario: especialmente para las funciones que realizan acciones, se recomienda incluir un paso en el que el usuario confirme la acción antes de la ejecución.

Para obtener más información sobre nuestras recomendaciones sobre cómo usar Azure modelos openAI de forma responsable, consulte la Información general de prácticas de inteligencia artificial responsable para Azure modelos openAI.

Importante

Los parámetros functions y function_call han quedado en desuso con la versión de 2023-12-01-preview de la API. El reemplazo para functions es el parámetro tools. El reemplazo para function_call es el parámetro tool_choice.

Compatibilidad con llamadas a funciones

Llamada a funciones paralelas

  • gpt-4 (2024-04-09)
  • gpt-4o (2024-05-13)
  • gpt-4o (2024-08-06)
  • gpt-4o (2024-11-20)
  • gpt-4o-mini (2024-07-18)
  • gpt-4.1 (2025-04-14)
  • gpt-4.1-mini (2025-04-14)
  • gpt-5 (2025-08-07)
  • gpt-5-mini (2025-08-07)
  • gpt-5-nano (2025-08-07)
  • gpt-5-codex (2025-09-11)
  • gpt-5.1 (2025-11-13)
  • gpt-5.1-chat (2025-11-13)
  • gpt-5.1-codex (2025-11-13)
  • gpt-5.1-codex-mini (2025-11-13)
  • gpt-5.1-codex-max (2025-12-04)
  • gpt-5.2 (2025-12-11)
  • gpt-5.2-chat (2025-12-11)
  • gpt-5.2-codex (2026-01-14)
  • gpt-5.2-chat (2026-02-10)
  • gpt-5.3-codex (2026-02-24)
  • gpt-5.3-chat (2026-03-03)
  • gpt-5.4 (2026-03-05)
  • gpt-5.4 (2026-03-05)
  • gpt-5.4-mini (2026-03-17)
  • gpt-5.4-nano (2026-03-17)
  • gpt-5.5 (2026-04-24)

La compatibilidad con la función paralela se agregó por primera vez en la versión de API 2023-12-01-preview

Invocación de funciones básicas con herramientas

  • Todos los modelos que admiten llamadas a funciones paralelas
  • gpt-5.4-pro (2026-03-05)
  • gpt-5-pro (2025-10-06)
  • codex-mini (2025-05-16)
  • o3-pro (2025-06-10)
  • o4-mini (2025-04-16)
  • o3 (2025-04-16)
  • gpt-4.1-nano (2025-04-14)
  • o3-mini (2025-01-31)
  • o1 (2024-12-17)

Nota

El tool_choice parámetro ahora se admite con o3-mini y o1. Para obtener más información, consulte la guía de modelos de razonamiento.

Importante

Las descripciones de herramientas y funciones están limitadas actualmente a 1024 caracteres con Azure OpenAI. Actualizaremos este artículo si se cambia este límite.

Pasos siguientes

  • Last updated on