Funciones personalizadas (llamada a funciones)
En esta página
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:
- Declaración: Describes tus funciones (nombre, descripción, parámetros) en la solicitud.
- Llamada: El modelo genera una llamada a función con los argumentos adecuados y pausa la generación.
- 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
argumentses una cadena JSON que debe analizarse en el lado del cliente. - Devuelve los errores como resultados para que el modelo pueda adaptarse.