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

Definir herramientas en JSON

Lección 4 de 14 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. De la teoría a la práctica
  2. Estructura de la solicitud con herramientas
  3. Cifras clave de la implementación
  4. Gestionar la respuesta tool_call
  5. Ejecutar y devolver el resultado
  6. Definir múltiples herramientas
  7. Comprobar finish_reason
  8. Puntos clave

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

200
Herramientas máximas por solicitud
6
Tipos JSON compatibles
3
SDK compatibles
1
Solicitud = flujo completo

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 messages y tools (definiciones)
  • Los argumentos de tool_call son una cadena JSON que hay que analizar
  • Envía el resultado en un mensaje con rol tool incluyendo el tool_call_id
  • Comprueba finish_reason para saber si el modelo está esperando un resultado
  • Puedes declarar múltiples herramientas; el modelo elige automáticamente