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

Funciones personalizadas (llamada a funciones)

Lección 11 de 16 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Conecta Grok a tus propios servicios
  2. Cómo funciona
  3. Declarar una función
  4. Recibir la llamada a la función
  5. Devolver el resultado
  6. Mejores prácticas para las descripciones
  7. Gestión de errores
  8. Puntos clave

Conecta Grok a tus propios servicios

Las herramientas del servidor (web_search, x_search, code_interpreter) son útiles, pero están limitadas a los servicios de xAI. Con herramientas personalizadas de tipo function, puedes conectar Grok a cualquier API o servicio de tu infraestructura.

Cómo funciona

La llamada a funciones sigue un ciclo de tres pasos:

  1. Declaración: Describes tus funciones (nombre, descripción, parámetros) en la solicitud.
  2. Llamada: El modelo genera una llamada a función con los argumentos adecuados y pausa la generación.
  3. Resultado: Tu código ejecuta la función y luego envías el resultado de vuelta al modelo para que pueda formular su respuesta.

Declarar una función

{
  "model": "grok-4.20-0309-reasoning",
  "input": "Resérvame una mesa para 2 personas esta noche a las 20:00.",
  "tools": [{
    "type": "function",
    "name": "book_restaurant",
    "description": "Reserva una mesa en un restaurante",
    "parameters": {
      "type": "object",
      "properties": {
        "restaurant_name": {
          "type": "string",
          "description": "Nombre del restaurante"
        },
        "date": {
          "type": "string",
          "description": "Fecha en formato AAAA-MM-DD"
        },
        "time": {
          "type": "string",
          "description": "Hora en formato HH:MM"
        },
        "guests": {
          "type": "integer",
          "description": "Número de comensales"
        }
      },
      "required": ["date", "time", "guests"]
    }
  }]
}

La descripción de cada función y parámetro es crucial. El modelo las utiliza para decidir cuándo llamar a la función y cómo rellenar los argumentos.

Recibir la llamada a la función

Cuando el modelo decide llamar a tu función, la respuesta contiene un elemento function_call:

{
  "id": "resp-xyz789",
  "status": "completed",
  "output": [{
    "type": "function_call",
    "name": "book_restaurant",
    "arguments": "{\"date\": \"2026-04-03\", \"time\": \"20:00\", \"guests\": 2}",
    "call_id": "call-abc123"
  }]
}

El campo arguments es una cadena JSON que debes analizar. El call_id identifica esta llamada específica.

Devolver el resultado

Tras ejecutar la función en tu código, devuelve el resultado:

import json

# 1. Solicitud inicial
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="¿Qué tiempo hace en París?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Obtiene el tiempo actual",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }]
)

# 2. Comprobar si el modelo quiere llamar a una función
for item in response.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)

        # 3. Ejecutar tu función
        weather_data = get_weather_from_api(args["city"])

        # 4. Devolver el resultado al modelo
        final = client.responses.create(
            model="grok-4.20-0309-reasoning",
            input=[{
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(weather_data)
            }],
            previous_response_id=response.id
        )
        print(final.output[0].content[0].text)

Mejores prácticas para las descripciones

El modelo depende de las descripciones para entender tus funciones. Sé preciso:

{
  "name": "search_products",
  "description": "Busca productos en el catálogo de comercio electrónico. Devuelve los 10 primeros resultados ordenados por relevancia. Admite búsquedas por nombre, categoría o rango de precios.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Términos de búsqueda (nombre del producto, marca, palabra clave)"
      },
      "category": {
        "type": "string",
        "enum": ["electronics", "clothing", "home", "sports"],
        "description": "Categoría de producto para filtrar"
      },
      "max_price": {
        "type": "number",
        "description": "Precio máximo en euros"
      }
    },
    "required": ["query"]
  }
}

Utiliza enum para valores predefinidos, una description detallada para cada parámetro y marca como required solo los parámetros esenciales.

Gestión de errores

Si tu función falla, devuelve el error como resultado:

try:
    result = call_external_api(args)
    output = json.dumps(result)
except Exception as e:
    output = json.dumps({"error": str(e)})

final = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input=[{
        "type": "function_call_output",
        "call_id": call_id,
        "output": output
    }],
    previous_response_id=response.id
)

El modelo interpreta el error y puede reformular su respuesta o intentar un enfoque diferente.

Puntos clave

  • Las funciones personalizadas conectan Grok a tus propios servicios.
  • El ciclo es: declarar, recibir la llamada, ejecutar, devolver el resultado.
  • Las descripciones de funciones y parámetros guían la elección del modelo.
  • El campo arguments es una cadena JSON que debe analizarse en el lado del cliente.
  • Devuelve los errores como resultados para que el modelo pueda adaptarse.