Tool-Calling
Qué cubre este artículo sobre Tool-Calling
- Qué es Tool-Calling y por qué marca la diferencia entre un chatbot simple y un agente de verdad
- Cómo funciona el flujo, desde la entrada del usuario hasta la respuesta final
- Cómo definir tu propio tool en Python y hacer que el modelo lo invoque
- Cómo proporcionar múltiples tools simultáneamente y dejar que el modelo elija
- Cómo utilizar Tool-Calling con modelos locales a través de Ollama
Introducción: Tool-Calling explicado de forma clara
Un modelo de lenguaje por sí solo solo puede generar texto. Conoce palabras, patrones y relaciones de su entrenamiento, pero no puede consultar una base de datos, leer un archivo ni enviar un correo. Aquí es donde entra en juego Tool-Calling. Con Tool-Calling, le das a un modelo la capacidad de invocar funciones externas y así ir más allá de su propio conocimiento.
Esta es la diferencia fundamental entre un chatbot simple y un agente de IA. Un chatbot responde preguntas con lo que ha aprendido. Un agente utiliza tools para obtener datos actuales, realizar cálculos o desencadenar acciones en el mundo real. Si quieres entender cómo trabajan realmente los agentes, no hay forma de evitar Tool-Calling. Encontrarás más detalles en Qué es un agente de IA y Chatbot vs. Agente de IA.
¿Por qué necesito Tool-Calling?
Imagina que le preguntas a un modelo de lenguaje: “¿Cómo está el clima ahora en Hamburgo?” Sin tools, el modelo tiene que adivinar o confiar en lo que aprendió durante el entrenamiento. Pero el clima de hoy no estaba disponible cuando se entrenó el modelo. La respuesta será entonces incorrecta o vaga.
Con Tool-Calling funciona diferente. Defines una función que consulta una API meteorológica. El modelo reconoce que necesita esta función y te devuelve el nombre de la función junto con el parámetro “Hamburgo”. Tu código ejecuta la función, obtiene el resultado meteorológico real y se lo devuelve al modelo. El modelo formula una respuesta natural como “En Hamburgo hace actualmente 14 grados y llueve ligeramente.”
Sin tools, un modelo está limitado a su entrenamiento. Con tools, puede acceder a datos actuales, archivos, bases de datos y APIs. Este es el paso decisivo que convierte un generador de texto en un sistema que realmente hace cosas.
Tool-Calling en pocas palabras
Tool-Calling significa que el modelo no genera directamente una respuesta, sino un mensaje estructurado que especifica qué función quiere invocar y con qué parámetros. Tu programa ejecuta la función y devuelve el resultado al modelo. El modelo utiliza ese resultado para formular una respuesta comprensible.
El ejemplo clásico es la consulta meteorológica:
- Defines un tool
get_weathercon el parámetrolocation. - El usuario pregunta por el clima en Berlín.
- El modelo devuelve: Invoca
get_weatherconlocation = "Berlin". - Tu código ejecuta la función y obtiene el resultado, por ejemplo “14 grados, lluvia”.
- Devuelves ese resultado al modelo.
- El modelo formula la respuesta final para el usuario.
El modelo nunca ejecuta la función por sí mismo. Solo te dice qué función necesita y con qué parámetros. La ejecución siempre ocurre en tu código. Esto es importante porque significa que tienes control total sobre lo que sucede.
¿Para quién es Tool-Calling?
Tool-Calling está dirigido a desarrolladores que quieren construir más que un chatbot simple. Si deseas desarrollar un agente que acceda a datos reales, ejecute acciones o se comunique con otros sistemas, necesitas Tool-Calling.
Los escenarios típicos incluyen:
- Construyes un agente que obtiene información actual de Internet.
- Quieres que un modelo acceda a tu almacenamiento local de archivos o base de datos.
- Desarrollas un asistente que crea citas o envía correos electrónicos.
- Utilizas un framework como LangGraph o CrewAI y quieres entender qué sucede bajo el capó. Más en Frameworks.
No necesitas años de experiencia en desarrollo de IA, pero deberías tener conocimientos básicos de programación, idealmente en Python. Los ejemplos en este artículo están estructurados para que puedas seguirlos paso a paso.
Términos importantes relacionados con Tool-Calling
| Término | Significado |
|---|---|
| Tool | Una función externa que el modelo puede invocar, por ejemplo una consulta meteorológica |
| Schema | La descripción formal de un tool con nombre, parámetros y propósito |
| Function Calling | Otro término para Tool-Calling, frecuentemente usado por OpenAI |
| Parameter | Los argumentos que el modelo pasa al tool, por ejemplo un nombre de ubicación |
| Tool-Aufruf | La salida del modelo que solicita una función en lugar de una respuesta directa |
| JSON | El formato en el que los tool-calls y parámetros se estructuran |
| API | Una interfaz a través de la cual tu tool obtiene datos de servicios externos |
| MCP | Model Context Protocol, un estándar para conectar tools uniformemente a modelos |
¿Cómo funciona Tool-Calling paso a paso?
El flujo de Tool-Calling sigue un patrón claro. Cada paso es importante, y una vez que entiendes el principio, puedes aplicarlo a cualquier tipo de tool.
Paso 1: El usuario hace una pregunta.
El usuario escribe un mensaje, por ejemplo “¿Cómo está el clima en Múnich?” Este mensaje entra en la lista de mensajes que pasas al modelo.
Paso 2: El modelo decide si necesita un tool.
El modelo no solo recibe el mensaje, sino también la lista de tools disponibles con sus esquemas. Analiza la pregunta y verifica si un tool puede ayudar. Si es así, decide hacer un tool-call. Si no, responde directamente.
Paso 3: El modelo devuelve un tool-call.
El tool-call es una salida estructurada, generalmente en formato JSON. Contiene el nombre de la función y los valores de los parámetros. El modelo no genera un texto de respuesta normal, sino esta instrucción estructurada.
Paso 4: Tu código ejecuta la función.
Ahora te toca a ti. Tu programa toma el tool-call, lee el nombre de la función y los parámetros, y ejecuta la función real. Esto puede ser una llamada a API, una consulta a base de datos o un cálculo.
Paso 5: El resultado vuelve al modelo.
Tomas el resultado de la función y lo añades a la lista de mensajes como un nuevo mensaje, típicamente con el rol “tool”. Luego invocas el modelo de nuevo.
Paso 6: El modelo formula la respuesta.
El modelo ve el resultado y formula una respuesta natural para el usuario. De “14 grados, lluvia” se convierte en “En Múnich hace actualmente 14 grados y llueve.”
Este ciclo puede repetirse si el modelo decide que necesita invocar más tools. En tareas complejas, un agente puede ejecutar múltiples tool-calls uno tras otro.
Ejemplo: Python con una herramienta simple
Veamos todo el flujo en Python. Usamos la API compatible con OpenAI porque es ampliamente soportada y la mayoría de frameworks y soluciones locales como Ollama la implementan.
import json
from openai import OpenAI
client = OpenAI()
# Paso 1: Definir la función real
def get_weather(location: str) -> str:
# En una aplicación real, llamarías a una API aquí.
# En este ejemplo, devolvemos un valor fijo.
return f"El clima en {location} es soleado y 22 grados."
# Paso 2: Definir el esquema de la herramienta
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Devuelve el clima actual para una ubicación.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "Nombre de la ubicación, por ejemplo 'Berlín'"
}
},
"required": ["location"]
}
}
}
]
# Paso 3: Preparar el mensaje del usuario
messages = [
{"role": "user", "content": "¿Cómo es el clima en Múnich?"}
]
# Paso 4: Llamar al modelo con herramientas
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Paso 5: Verificar si el modelo quiere invocar una herramienta
tool_calls = response.choices[0].message.tool_calls
if tool_calls:
# Añadir la respuesta del modelo a la lista de mensajes
messages.append(response.choices[0].message)
for tool_call in tool_calls:
# Extraer el nombre de la función y los parámetros
function_name = tool_call.function.name
arguments = json.loads(tool_call.function.arguments)
# Ejecutar la función
if function_name == "get_weather":
result = get_weather(**arguments)
else:
result = "Función desconocida."
# Añadir el resultado a la lista de mensajes
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": result
})
# Paso 6: Llamar al modelo nuevamente para que formule la respuesta
final_response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
else:
# Si no se llama a ninguna herramienta, responder directamente
print(response.choices[0].message.content)Repasemos esto paso a paso.
Primero definimos la función get_weather. Toma una ubicación como parámetro y devuelve una cadena de texto. En una aplicación real, aquí llamarías a una API meteorológica como OpenWeatherMap. En este ejemplo, simplemente devolvemos un texto fijo.
Luego definimos el esquema de la herramienta. El esquema le dice al modelo cómo se llama la función, qué hace y qué parámetros espera. La description es especialmente importante porque el modelo la usa para decidir si la herramienta es relevante para una pregunta. Cuanto más precisa sea la descripción, mejor será su decisión.
La lista de mensajes messages contiene la pregunta del usuario. La pasamos junto con las herramientas al modelo. El parámetro tool_choice con el valor auto significa que el modelo puede decidir por sí mismo si invoca una herramienta o responde directamente.
Después de la llamada, verificamos si tool_calls está presente en la respuesta. Si lo está, añadimos la respuesta del modelo a la lista de mensajes e iteramos sobre cada invocación de herramienta. Extraemos el nombre de la función y los parámetros, ejecutamos la función y añadimos el resultado con el rol tool a la lista de mensajes.
Al final, llamamos al modelo nuevamente, esta vez con el resultado en la lista de mensajes. El modelo formula la respuesta natural y la devuelve.
Ejemplo: Varias herramientas
En la práctica, rara vez tienes solo una herramienta. Un agente podría consultar el clima, determinar la hora y realizar cálculos. Veamos cómo definir varias herramientas y dejar que el modelo las elija.
import json
from openai import OpenAI
client = OpenAI()
def get_weather(location: str) -> str:
return f"El clima en {location} es nublado y 18 grados."
def get_time(timezone: str) -> str:
return f"La hora actual en {timezone} es 14:30."
def calculate(expression: str) -> str:
try:
result = eval(expression)
return f"Resultado: {result}"
except Exception:
return "Expresión inválida."
# Un diccionario que mapea nombres de funciones a funciones Python
available_functions = {
"get_weather": get_weather,
"get_time": get_time,
"calculate": calculate
}
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Devuelve el clima actual para una ubicación.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "Nombre de la ubicación"}
},
"required": ["location"]
}
}
},
{
"type": "function",
"function": {
"name": "get_time",
"description": "Devuelve la hora actual para una zona horaria.",
"parameters": {
"type": "object",
"properties": {
"timezone": {"type": "string", "description": "Zona horaria, por ejemplo 'Europe/Berlin'"}
},
"required": ["timezone"]
}
}
},
{
"type": "function",
"function": {
"name": "calculate",
"description": "Realiza un cálculo matemático.",
"parameters": {
"type": "object",
"properties": {
"expression": {"type": "string", "description": "Expresión matemática, por ejemplo '2 + 3 * 4'"}
},
"required": ["expression"]
}
}
}
]
messages = [
{"role": "user", "content": "¿Cómo es el clima en Colonia y qué hora es en Europe/Berlin?"}
]
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
tools=tools,
tool_choice="auto"
)
tool_calls = response.choices[0].message.tool_calls
if tool_calls:
messages.append(response.choices[0].message)
for tool_call in tool_calls:
function_name = tool_call.function.name
arguments = json.loads(tool_call.function.arguments)
# Obtener la función del diccionario y ejecutarla
function = available_functions.get(function_name)
if function:
result = function(**arguments)
else:
result = "Función desconocida."
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": result
})
final_response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
tools=tools
)
print(final_response.choices[0].message.content)
else:
print(response.choices[0].message.content)Aquí definimos tres funciones: get_weather, get_time y calculate. Cada una obtiene su propio esquema en la lista tools. El diccionario available_functions asigna los nombres de las funciones a las funciones reales de Python. Esto hace el código más limpio porque no necesitamos una consulta if separada para cada función.
La pregunta del usuario menciona dos cosas: el clima y la hora. El modelo puede decidir solicitar ambas herramientas en una única llamada. El bucle sobre tool_calls ejecuta entonces ambas funciones y añade ambos resultados a la lista de mensajes. Al final, el modelo formula una respuesta que contiene ambas informaciones.
Importante: la description de cada herramienta debe estar claramente formulada. Si dos herramientas tienen descripciones similares, el modelo puede elegir la incorrecta. Dedica tiempo a escribir buenas descripciones.
Tool-Calling con Ollama
No necesitas una API en la nube para utilizar Tool-Calling. Con Ollama puedes ejecutar modelos localmente en tu propio ordenador. Esto es especialmente relevante cuando procesas datos sensibles o prefieres no depender de servicios externos. Encontrarás más motivación en ¿Qué es la IA local?.
Ollama soporta Tool-Calling con ciertos modelos, por ejemplo llama3.1 o qwen2.5. Su API es compatible con OpenAI, lo que significa que puedes usar casi el mismo código.
import json
import requests
# Ollama se ejecuta por defecto en localhost:11434
OLLAMA_URL = "http://localhost:11434/api/chat"
def get_weather(location: str) -> str:
return f"Das Wetter in {location} ist sonnig und 22 Grad."
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Gibt das aktuelle Wetter für einen Ort zurück.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "Name des Ortes"}
},
"required": ["location"]
}
}
}
]
messages = [
{"role": "user", "content": "Wie ist das Wetter in Berlin?"}
]
# Ersten Aufruf an Ollama senden
response = requests.post(OLLAMA_URL, json={
"model": "llama3.1",
"messages": messages,
"tools": tools,
"stream": False
})
data = response.json()
message = data.get("message", {})
# Prüfen, ob das Modell ein Tool aufrufen will
if "tool_calls" in message and message["tool_calls"]:
messages.append(message)
for tool_call in message["tool_calls"]:
function = tool_call["function"]
function_name = function["name"]
arguments = function["arguments"]
if function_name == "get_weather":
result = get_weather(**arguments)
else:
result = "Unbekannte Funktion."
messages.append({
"role": "tool",
"content": result
})
# Zweiten Aufruf mit dem Ergebnis
final_response = requests.post(OLLAMA_URL, json={
"model": "llama3.1",
"messages": messages,
"tools": tools,
"stream": False
})
final_data = final_response.json()
print(final_data["message"]["content"])
else:
print(message.get("content", ""))La estructura es casi idéntica a la del ejemplo de OpenAI. La diferencia principal es que utilizamos requests para llamar directamente a la API de Ollama en lugar de usar el paquete Python de OpenAI. La URL del endpoint apunta al servidor Ollama local. La estructura de las herramientas y los mensajes es la misma.
Ten en cuenta que no todos los modelos locales manejan Tool-Calling con igual eficacia. Los modelos más grandes como llama3.1:8b o qwen2.5:14b son considerablemente más confiables que los modelos muy pequeños. Si el modelo no formatea correctamente la llamada a la herramienta, puede ayudarte elegir un modelo más grande o redactar las descripciones de las herramientas de forma más precisa.
Herramientas típicas para agentes de IA con Tool-Calling
Cuando empieces a construir agentes, descubrirás que ciertos tipos de herramientas aparecen una y otra vez. Aquí hay un resumen de las herramientas más frecuentes con ejemplos.
Búsqueda web: El agente busca información actual en Internet. Ejemplo: una función web_search(query) que llama a una API de búsqueda y devuelve los resultados principales. Útil para preguntas sobre eventos actuales o hechos que no están en el conocimiento de entrenamiento del modelo.
Acceso a archivos: El agente lee o escribe archivos en el sistema local. Ejemplo: read_file(path) lee el contenido de un archivo, write_file(path, content) lo escribe. Útil cuando el agente necesita trabajar con documentos almacenados en tu ordenador.
Consultas a base de datos: El agente ejecuta queries SQL. Ejemplo: query_database(sql) envía una consulta a una base de datos y devuelve los resultados. Útil para agentes que necesitan acceder a datos estructurados.
Envío de correos: El agente envía mensajes de correo electrónico. Ejemplo: send_email(to, subject, body) utiliza un servidor SMTP. Útil para asistentes que deben enviar notificaciones o reportes.
Calculadora: El agente realiza cálculos matemáticos. Ejemplo: calculate(expression) evalúa una expresión matemática. Útil porque los modelos de lenguaje suelen ser poco confiables en cálculos complejos.
Ejecución de código: El agente ejecuta código de programa. Ejemplo: run_python(code) ejecuta un script Python y devuelve la salida. Útil para agentes que deben analizar datos o generar scripts.
Cada una de estas herramientas conlleva riesgos. El envío de correos y la ejecución de código son particularmente sensibles porque tienen consecuencias reales. Siempre reflexiona sobre qué acciones puede realizar realmente un agente y qué aprobaciones son necesarias.
Escollos típicos en Tool-Calling
Tool-Calling parece sencillo al principio, pero en la práctica hay varios escollos que encontrarás. Aquí están los problemas más comunes.
El modelo llama a la herramienta incorrecta. Cuando las descripciones de las herramientas no son claras o varios tools son similares, el modelo puede elegir el incorrecto. Solución: redacta descripciones precisas y bien diferenciadas, y evita responsabilidades que se superpongan.
Los parámetros son incorrectos o incompletos. El modelo puede inventar parámetros que no están definidos en el esquema u omitir parámetros requeridos. Solución: define claramente los parámetros required y valida los parámetros en tu código antes de ejecutar la función.
El modelo alucina herramientas. A veces el modelo inventa funciones que no existen. Esto ocurre frecuentemente con modelos pequeños. Solución: siempre comprueba si el nombre de la función existe en tu lista de funciones disponibles antes de intentar llamarla.
Los modelos pequeños tienen dificultades con Tool-Calling. No todos los modelos pueden realizar Tool-Calling de forma confiable. Los modelos muy pequeños a menudo producen JSON incorrecto o no entienden adecuadamente las descripciones de herramientas. Solución: utiliza modelos que hayan sido explícitamente entrenados para Tool-Calling y prueba con diferentes tamaños de modelo.
Riesgos de seguridad por ejecución incontrolada. Si una herramienta realiza acciones sensibles, por ejemplo eliminar archivos o enviar correos, una llamada incorrecta puede causar daño real. Solución: limita las herramientas disponibles, valida todos los parámetros y requiere aprobación humana para acciones críticas.
Manejo deficiente de errores que oculta problemas. Si una herramienta falla y no devuelves correctamente el error al modelo, el modelo no puede reaccionar ante ello. Solución: captura errores y devuelve un mensaje de error claro al modelo para que pueda decidir qué hacer a continuación.
Hardware, costos y seguridad en Tool-Calling
Hardware: Tool-Calling en sí requiere pocos recursos. La parte que consume mucho cálculo es la inferencia del modelo. Si utilizas un modelo local a través de Ollama, necesitas suficiente RAM e idealmente una GPU, según el tamaño del modelo. Un modelo de 8B se ejecuta en un portátil moderno con 16 GB de RAM, mientras que modelos más grandes como 14B o 32B requieren considerablemente más memoria.
Costos: Con APIs en la nube como OpenAI pagas por token. Tool-Calling significa llamadas API adicionales porque consultas el modelo nuevamente después de cada resultado de herramienta. Con varias herramientas por pregunta, los costos pueden aumentar. Con modelos locales a través de Ollama no hay costos de API, pero asumes los costos de hardware tú mismo.
Seguridad: Expón únicamente las herramientas que el agente realmente necesita. Una herramienta que elimina archivos o ejecuta comandos a nivel de sistema solo debe usarse con aprobación adicional. Valida todos los parámetros que proporciona el modelo antes de usarlos. Utiliza sandboxing siempre que sea posible, especialmente para ejecución de código. Y recuerda que el modelo nunca ejecuta código en sí, solo sugiere qué se debe ejecutar. El control está en tus manos.
Enlaces y recursos adicionales sobre Tool-Calling
- ¿Qué es un agente de IA? - Fundamentos sobre agentes y cómo se diferencian de los chatbots
- Chatbot vs. agente de IA - Las diferencias entre chatbots simples y agentes reales
- Frameworks - Descripción general de frameworks como LangGraph y CrewAI que abstraen Tool-Calling
- Ollama - Ejecuta modelos locales y utiliza Tool-Calling sin la nube
- ¿Qué es la IA local? - Por qué los modelos locales son útiles y qué pueden hacer
Preguntas frecuentes sobre Tool-Calling
¿Todos los modelos soportan Tool-Calling?
No. Los modelos deben estar entrenados explícitamente para llamadas a funciones. Muchos modelos modernos como Llama 3.1, Qwen 2.5 y Mistral lo dominan, pero los modelos muy pequeños o antiguos a menudo no pueden hacerlo de manera confiable. Consulta la documentación del modelo específico.
¿Puedo definir múltiples herramientas a la vez?
Sí. Pasas una lista de herramientas. El modelo selecciona la apropiada o solicita múltiples llamadas en una única respuesta. Debes asegurar que las descripciones de las herramientas sean claras, para que el modelo no se confunda.
¿Debe la herramienta responder de forma síncrona?
No necesariamente. Puedes usar herramientas asincrónicas, siempre que el resultado se devuelva al modelo antes de generar la siguiente respuesta. En Python, puedes usar funciones async, pero debes asegurar que esperes el resultado.
¿Cómo aseguro las herramientas?
Limita las herramientas disponibles a lo necesario, valida todos los parámetros, establece permisos y utiliza sandboxing. Las acciones críticas como envío de correos o eliminación de archivos deben requerir aprobación humana. Nunca concedas acceso ilimitado al sistema.
¿Qué ocurre si el modelo alucina una herramienta?
Significa que el modelo inventa un nombre de función que no está en tu lista de herramientas. En tu código, siempre verifica que el nombre de función existe antes de intentar llamarlo. Si no existe, devuelve un mensaje de error al modelo para que lo intente de nuevo.
¿Puede un modelo llamar múltiples herramientas secuencialmente?
Sí. En tareas complejas, el modelo puede decidir, después del primer resultado de herramienta, que necesita otra. Implementas un bucle que continúa hasta que el modelo no solicite más llamadas a herramientas.
¿Necesito un framework para Tool-Calling?
No. Puedes implementar Tool-Calling directamente con la API del proveedor del modelo, como se muestra en los ejemplos de este artículo. Sin embargo, frameworks como LangGraph o CrewAI te ahorran trabajo repetitivo y ofrecen características adicionales como manejo de errores y lógica de bucles.
¿Funciona Tool-Calling con modelos locales?
Sí, con limitaciones. Ollama soporta Tool-Calling para ciertos modelos como Llama 3.1 y Qwen 2.5. La confiabilidad depende del tamaño del modelo. Los modelos muy pequeños a menudo producen JSON incorrecto o llaman herramientas equivocadas.
¿Cuántas herramientas puedo definir a la vez?
Teóricamente ilimitadas, pero en la práctica la precisión sufre si ofreces demasiadas. El modelo debe procesar todas las descripciones y tomar la decisión correcta. Comienza con pocas herramientas y expande gradualmente.
¿Cuál es la diferencia entre Function Calling y Tool-Calling?
Los términos se usan generalmente como sinónimos. OpenAI ha usado tradicionalmente “Function Calling”, mientras que documentación más reciente y otros proveedores prefieren “Tool-Calling”. Ambos significan lo mismo: el modelo indica qué función quiere llamar, y tu código la ejecuta.
¿Puede el modelo inventar parámetros que no definí?
Sí, especialmente en modelos más pequeños. Tu código debe usar solo los parámetros definidos en el esquema e ignorar cualquier parámetro adicional. Valida los parámetros antes de pasarlos a la función.
Fuentes y lecturas adicionales
- OpenAI Function Calling Documentación
- Ollama Tool-Support Dokumentación
- LangGraph Tools Dokumentación
- Model Context Protocol (MCP) Spezifikation