Definir herramientas en JSON
En esta página
De la teoría a la práctica
Ya conoces el concepto de llamada a funciones y la estructura de los esquemas JSON. Es hora de pasar a la implementación concreta. En esta lección aprenderás a construir una solicitud completa con definiciones de herramientas y a gestionar la respuesta del modelo.
Estructura de la solicitud con herramientas
Aquí tienes una solicitud completa a la API de Grok con una herramienta definida:
from openai import OpenAI
client = OpenAI(
api_key="your-api-key",
base_url="https://api.x.ai/v1"
)
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Obtener el tiempo actual para una ciudad",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Nombre de la ciudad"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius"
}
},
"required": ["city"]
}
}
}
]
response = client.chat.completions.create(
model="grok-4.5",
messages=[
{"role": "user", "content": "¿Qué tiempo hace en París?"}
],
tools=tools
)
Observa la estructura anidada: el objeto tools contiene un array, donde cada elemento tiene un type y un objeto function con los detalles.
Cifras clave de la implementación
Gestionar la respuesta tool_call
Cuando el modelo decide llamar a una función, la respuesta contiene un array tool_calls:
message = response.choices[0].message
if message.tool_calls:
for tool_call in message.tool_calls:
print(f"Función: {tool_call.function.name}")
print(f"Argumentos: {tool_call.function.arguments}")
print(f"ID: {tool_call.id}")
El campo tool_call.function.arguments es una cadena JSON (no un objeto Python). Debes analizarla:
import json
args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")
Ejecutar y devolver el resultado
Una vez ejecutada la función, envías el resultado de vuelta al modelo en una segunda llamada:
import json
# 1. Ejecutar la función
weather_data = get_weather(city="París", unit="celsius")
# 2. Construir los mensajes con el resultado
messages = [
{"role": "user", "content": "¿Qué tiempo hace en París?"},
message, # La respuesta del modelo con tool_calls
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(weather_data)
}
]
# 3. Volver a llamar al modelo con el resultado
final_response = client.chat.completions.create(
model="grok-4.5",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
El mensaje con el rol tool debe contener:
tool_call_id: el identificador único del tool_call (para vincularlo a la solicitud)content: el resultado como una cadena JSON
Definir múltiples herramientas
Puedes declarar tantas herramientas como necesites en el array tools:
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Obtener el tiempo actual para una ciudad",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "search_restaurants",
"description": "Buscar restaurantes por ciudad y tipo de cocina",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "book_table",
"description": "Reservar una mesa en un restaurante",
"parameters": { ... }
}
}
]
El modelo elegirá automáticamente la herramienta o herramientas relevantes basándose en la solicitud del usuario.
Comprobar finish_reason
El campo finish_reason en la respuesta indica si el modelo ha terminado su respuesta o si está esperando un resultado de una herramienta:
finish_reason = response.choices[0].finish_reason
if finish_reason == "tool_calls":
# El modelo está esperando el resultado de una o más herramientas
handle_tool_calls(response)
elif finish_reason == "stop":
# El modelo ha terminado su respuesta
print(response.choices[0].message.content)
Puntos clave
- La solicitud contiene
messagesytools(definiciones) - Los argumentos de tool_call son una cadena JSON que hay que analizar
- Envía el resultado en un mensaje con rol
toolincluyendo eltool_call_id - Comprueba
finish_reasonpara saber si el modelo está esperando un resultado - Puedes declarar múltiples herramientas; el modelo elige automáticamente