Introducción

Un agente de IA se vuelve realmente útil solo cuando puede salir de su propia ventana de contexto. La llamada a herramientas es el mecanismo que permite a un modelo de lenguaje decidir que necesita obtener una fila de una base de datos, consultar una API del clima o disparar una acción en el servidor, y luego recibir el resultado como parte de su siguiente paso de razonamiento. En esta lección nos centramos en cómo diseñar ese bucle para que sea fiable dentro de una aplicación web.

Trataremos una herramienta como una función simple con tres cosas: un nombre estable, un esquema JSON que describa sus parámetros y una descripción que indique al modelo cuándo usarla. Todo lo demás es cableado en el frontend y el backend.

Esquema de herramientas y conceptos básicos de llamadas a funciones

La mayoría de las APIs modernas de LLM exponen la misma estructura. Le pasas un array de definiciones de herramientas, cada una con un nombre, una descripción y un esquema de parámetros. El modelo puede responder con una solicitud estructurada para llamar a una de esas herramientas, que tu backend luego ejecuta.

Aquí tienes una declaración de herramienta mínima en el estilo del SDK de Python de OpenAI. El esquema es lo que el modelo realmente lee para decidir qué argumentos producir.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city. Use when the user asks about weather, temperature, or conditions in a specific location.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name, e.g. 'Hanoi'"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["city"]
            }
        }
    }
]

Fíjate en tres decisiones de diseño que importan. Primero, la descripción es una instrucción corta que indica al modelo cuándo disparar la herramienta, escrita en el mismo tono que tu prompt de sistema. Segundo, los parámetros usan JSON Schema estándar para que los enums y los campos requeridos se apliquen. Tercero, los valores por defecto se omiten del esquema a menos que quieras que el modelo piense que son opcionales.

Conexión de herramientas al backend de una aplicación web

En una aplicación web real, el agente no se ejecuta dentro del navegador. El navegador envía la conversación a tu backend, el backend llama al LLM con la lista de herramientas, y cuando el modelo devuelve una llamada a herramienta, tu servidor la ejecuta contra tus propios servicios. El resultado se envía de vuelta al modelo como un mensaje de herramienta, y entonces el modelo produce la respuesta final.

Un handler mínimo de FastAPI se ve así. Detecta una llamada a herramienta en la respuesta, ejecuta la función Python correspondiente y devuelve la salida a la conversación.

from fastapi import FastAPI
from openai import OpenAI

app = FastAPI()
client = OpenAI()

def get_weather(city: str, unit: str = "celsius") -> dict:
    # call your real weather provider here
    return {"city": city, "unit": unit, "temp": 30, "condition": "sunny"}

dispatch = {"get_weather": get_weather}

@app.post("/chat")
def chat(messages: list):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=messages,
        tools=tools,
    )
    msg = response.choices[0].message
    if msg.tool_calls:
        for call in msg.tool_calls:
            fn = dispatch[call.function.name]
            args = json.loads(call.function.arguments)
            result = fn(**args)
            messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
        response = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=tools)
    return {"reply": response.choices[0].message.content}

El diccionario de despacho es el patrón más limpio para proyectos pequeños. Para sistemas más grandes, mueves el registro de herramientas a un objeto tipo registry para que se puedan añadir herramientas sin editar el handler.

Patrones de diseño de parámetros

La mayoría de los fallos en las herramientas vienen de un mal diseño de parámetros, no del modelo. Dos patrones reducen esto drásticamente.

Primero, prefiere parámetros planos en lugar de objetos anidados. Una herramienta que recibe campos separados lat y lon es más fácil de rellenar correctamente para un modelo que una que recibe un único objeto location anidado. Segundo, refleja el vocabulario que tus usuarios realmente usan. Si los usuarios dicen "código postal", expón un parámetro llamado zip_code, no postal_code.

{
  "name": "search_products",
  "description": "Search the product catalog by keyword and optional filters.",
  "parameters": {
    "type": "object",
    "properties": {
      "keyword": {"type": "string", "description": "Search term, e.g. 'running shoes'"},
      "max_price_usd": {"type": "number", "description": "Optional upper price limit in USD"},
      "in_stock_only": {"type": "boolean", "description": "If true, only return items currently in stock"}
    },
    "required": ["keyword"]
  }
}

Tres parámetros planos, uno obligatorio, el resto con valores por defecto razonables que el modelo puede dejar vacíos.

Errores comunes

Algunos errores aparecen en casi todas las integraciones. El modelo alucina un nombre de herramienta que no existe, así que siempre valida call.function.name contra tus herramientas registradas antes de despachar. El modelo pasa un string donde tu función espera un entero, así que fuerza los argumentos según el esquema antes de llamar. Y el agente entra en un bucle infinito de llamadas a herramientas porque cree que todavía necesita más información, así que limita el bucle a tres o cinco iteraciones y muestra una respuesta de respaldo si nunca converge.

Registrar cada llamada a herramienta con sus argumentos y resultado es el hábito de depuración con mayor impacto que puedes construir. Cuando algo se rompe en producción, ese log es cómo verás si el modelo eligió la herramienta equivocada, eligió la herramienta correcta con los argumentos incorrectos, o tu backend devolvió una estructura inesperada.

Resumen

La llamada a herramientas convierte un chatbot en un agente. Defines las herramientas como JSON Schema, las pasas en cada llamada al LLM, ejecutas lo que el modelo solicite en tu backend y devuelves el resultado como un mensaje de herramienta. Un buen diseño de parámetros es plano, usa el vocabulario del usuario y marca claramente los campos obligatorios. Valida siempre los nombres de herramientas, limita el bucle y registra todo. En la próxima lección añadimos planificación y razonamiento multi-paso encima de este bucle.