Herramientas: el bot toma acciones

"El modelo nunca toca tu base de datos. Solo pide, con buenos modales y en JSON, que vos lo hagás por él."

Qué vas a aprender en este capítulo

El bot del capítulo 2 conversa precioso, pero cuando le preguntan el precio de la pupusa de ayote dice "lo voy a confirmar"... y nunca confirma nada, porque no tiene cómo. En este capítulo le damos manos: la capacidad de consultar el menú real, calcular pedidos con aritmética exacta, registrarlos en disco y verificar horarios. Son los requisitos R1 a R4 del proyecto.

La técnica se llama tool use (o function calling) y es, junto con RAG, el patrón más importante del desarrollo con LLMs. Vas a aprender:

• El contrato exacto: cómo declarás herramientas (JSON Schema) y cómo el modelo pide usarlas.
• El loop agéntico: el ciclo request → tool_use → ejecutar → tool_result → respuesta, robusto ante varias tools por turno y ante errores.
• El oficio de escribir descripciones de herramientas que digan cuándo usarlas — la diferencia entre un bot que las usa con criterio y uno que las ignora o abusa.

3.1 Qué es function calling (y qué no es)

3.2 Los datos: el menú de La Esquina

Las herramientas necesitan datos reales sobre los que operar. En producción esto sería una base de datos; para el libro, un módulo Python con diccionarios — la interfaz de las herramientas no cambia cuando migrés a SQL. Creá datos_la_esquina.py:

"""Datos de La Esquina: menu, sucursales y registro de pedidos."""
import json
from datetime import datetime
from pathlib import Path

MENU = {
    "pupusas": {
        "queso": 0.75,
        "frijol con queso": 0.75,
        "chicharron": 0.85,
        "revuelta": 0.85,
        "ayote": 0.85,
        "jalapeño con queso": 0.90,
        "loroco con queso": 0.90,
        "camaron": 1.25,
    },
    "bebidas": {
        "horchata": 1.00,
        "ensalada": 1.00,
        "cafe": 0.75,
        "gaseosa": 1.00,
        "agua": 0.50,
    },
    "extras": {
        "curtido extra": 0.25,
        "salsa extra": 0.25,
        "queso fundido": 1.50,
    },
}

HORARIOS = {
    "centro":      {"abre": 7,  "cierra": 20, "dias": "lunes a domingo"},
    "roosevelt":   {"abre": 10, "cierra": 21, "dias": "lunes a domingo"},
    "metrocentro": {"abre": 9,  "cierra": 19, "dias": "lunes a sábado"},
}

ARCHIVO_PEDIDOS = "pedidos.json"


def buscar_precio(nombre_item: str):
    """Busca un item por nombre en todo el menu. Devuelve (categoria, precio) o None."""
    nombre = nombre_item.lower().strip()
    for categoria, items in MENU.items():
        if nombre in items:
            return categoria, items[nombre]
    return None


def guardar_pedido(pedido: dict) -> int:
    """Agrega un pedido al archivo JSON y devuelve su numero."""
    ruta = Path(ARCHIVO_PEDIDOS)
    pedidos = json.loads(ruta.read_text(encoding="utf-8")) if ruta.exists() else []
    pedido["numero"] = len(pedidos) + 1
    pedido["registrado_en"] = datetime.now().isoformat(timespec="seconds")
    pedidos.append(pedido)
    ruta.write_text(json.dumps(pedidos, ensure_ascii=False, indent=2),
                    encoding="utf-8")
    return pedido["numero"]

3.3 Definir las herramientas: JSON Schema + descripciones que enseñan

Acá está el corazón del capítulo. Cada herramienta se declara con un dict. Prestá especial atención a las description: no describen solo qué hace la herramienta, sino cuándo usarla — esa es la señal que el modelo usa para decidir. Creá herramientas.py:

"""Definiciones (schemas) e implementaciones de las herramientas del bot."""
import json
from datetime import datetime

import datos_la_esquina as datos

# ---------------------------------------------------------------
# 1. SCHEMAS: lo que el modelo ve. Las descripciones dicen CUANDO usarlas.
# ---------------------------------------------------------------

TOOLS = [
    {
        "name": "consultar_menu",
        "description": (
            "Devuelve los platillos y precios del menú de La Esquina. "
            "Usala SIEMPRE que el cliente pregunte qué hay, precios, o "
            "mencione un platillo — nunca respondas precios de memoria. "
            "Si el cliente pregunta por algo general ('¿qué venden?'), "
            "consultá sin categoría para traer todo."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "categoria": {
                    "type": "string",
                    "enum": ["pupusas", "bebidas", "extras"],
                    "description": "Categoría a consultar. Omitila para traer el menú completo.",
                },
            },
            "required": [],
        },
    },
    {
        "name": "calcular_pedido",
        "description": (
            "Calcula el total exacto de un pedido con los precios oficiales. "
            "Usala SIEMPRE antes de decirle un total al cliente — no hagás "
            "aritmética vos. También sirve para verificar que los items "
            "existan en el menú antes de confirmar."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "items": {
                    "type": "array",
                    "description": "Items del pedido con su cantidad.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "nombre": {
                                "type": "string",
                                "description": "Nombre del item tal como aparece en el menú, p. ej. 'revuelta'.",
                            },
                            "cantidad": {
                                "type": "integer",
                                "description": "Cuántas unidades. Mínimo 1.",
                            },
                        },
                        "required": ["nombre", "cantidad"],
                    },
                },
            },
            "required": ["items"],
        },
    },
    {
        "name": "registrar_pedido",
        "description": (
            "Registra un pedido confirmado en el sistema y devuelve el número "
            "de pedido. Usala SOLO cuando ya tengás los tres datos: items, "
            "nombre del cliente y sucursal, Y el cliente haya confirmado "
            "explícitamente que quiere ordenar. NUNCA la uses para cotizar."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "items": {
                    "type": "array",
                    "description": "Items confirmados del pedido.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "nombre": {"type": "string"},
                            "cantidad": {"type": "integer"},
                        },
                        "required": ["nombre", "cantidad"],
                    },
                },
                "nombre_cliente": {
                    "type": "string",
                    "description": "Nombre de quien recoge el pedido.",
                },
                "sucursal": {
                    "type": "string",
                    "enum": ["centro", "roosevelt", "metrocentro"],
                    "description": "Sucursal donde se recoge.",
                },
            },
            "required": ["items", "nombre_cliente", "sucursal"],
        },
    },
    {
        "name": "verificar_horario",
        "description": (
            "Devuelve el horario de una sucursal y si está abierta en este "
            "momento. Usala cuando pregunten horarios, si están abiertos, o "
            "a qué hora cierran. No adivines horarios."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "sucursal": {
                    "type": "string",
                    "enum": ["centro", "roosevelt", "metrocentro"],
                    "description": "Sucursal a verificar.",
                },
            },
            "required": ["sucursal"],
        },
    },
]

# ---------------------------------------------------------------
# 2. IMPLEMENTACIONES: el Python real que se ejecuta.
# ---------------------------------------------------------------

def consultar_menu(categoria: str | None = None) -> str:
    if categoria:
        items = datos.MENU.get(categoria)
        if items is None:
            raise ValueError(f"Categoría desconocida: {categoria!r}")
        return json.dumps({categoria: items}, ensure_ascii=False)
    return json.dumps(datos.MENU, ensure_ascii=False)


def calcular_pedido(items: list[dict]) -> str:
    detalle, total, no_encontrados = [], 0.0, []
    for item in items:
        nombre = item["nombre"]
        cantidad = int(item["cantidad"])
        if cantidad < 1:
            raise ValueError(f"Cantidad inválida para {nombre!r}: {cantidad}")
        resultado = datos.buscar_precio(nombre)
        if resultado is None:
            no_encontrados.append(nombre)
            continue
        _, precio = resultado
        subtotal = round(precio * cantidad, 2)
        total += subtotal
        detalle.append({"item": nombre, "cantidad": cantidad,
                        "precio_unitario": precio, "subtotal": subtotal})
    return json.dumps({
        "detalle": detalle,
        "total": round(total, 2),
        "items_no_encontrados": no_encontrados,
    }, ensure_ascii=False)


def registrar_pedido(items: list[dict], nombre_cliente: str, sucursal: str) -> str:
    # Re-validamos TODO en el servidor: nunca confíes solo en el modelo.
    calculo = json.loads(calcular_pedido(items))
    if calculo["items_no_encontrados"]:
        raise ValueError(
            f"Items fuera del menú: {calculo['items_no_encontrados']}. "
            "No se registró el pedido."
        )
    if not nombre_cliente.strip():
        raise ValueError("Falta el nombre del cliente.")
    numero = datos.guardar_pedido({
        "items": calculo["detalle"],
        "total": calculo["total"],
        "cliente": nombre_cliente.strip(),
        "sucursal": sucursal,
    })
    return json.dumps({"numero_pedido": numero, "total": calculo["total"],
                       "sucursal": sucursal}, ensure_ascii=False)


def verificar_horario(sucursal: str) -> str:
    info = datos.HORARIOS.get(sucursal)
    if info is None:
        raise ValueError(f"Sucursal desconocida: {sucursal!r}")
    hora_actual = datetime.now().hour
    abierta = info["abre"] <= hora_actual < info["cierra"]
    return json.dumps({
        "sucursal": sucursal,
        "horario": f"{info['abre']}:00 a {info['cierra']}:00, {info['dias']}",
        "abierta_ahora": abierta,
    }, ensure_ascii=False)


# Registro nombre → funcion, usado por el loop del bot.
IMPLEMENTACIONES = {
    "consultar_menu": consultar_menu,
    "calcular_pedido": calcular_pedido,
    "registrar_pedido": registrar_pedido,
    "verificar_horario": verificar_horario,
}

3.4 El loop agéntico completo

Ahora conectamos las herramientas al bot del capítulo 2. El método nuevo, enviar(), implementa el ciclo del diagrama: llama a la API en un while, y mientras el modelo siga pidiendo herramientas, las ejecuta y le devuelve resultados. Creá bot_v3.py:

"""Bot de La Esquina v3: memoria + personalidad + HERRAMIENTAS (tool use)."""
import json
from pathlib import Path

from dotenv import load_dotenv
import anthropic

from herramientas import TOOLS, IMPLEMENTACIONES

load_dotenv()

MAX_TURNOS = 30          # los ciclos de tools agregan turnos; damos mas margen
MAX_CICLOS_TOOLS = 8     # tope de iteraciones del loop agentico por mensaje

SYSTEM_PROMPT = """Sos "Esquinita", el asistente virtual de La Esquina, pupusería \
con 3 sucursales en San Miguel, El Salvador.

# Tu rol
Atendés clientes por chat: menú, precios, horarios y pedidos.

# Herramientas
Tenés herramientas para consultar el menú, calcular totales, registrar pedidos
y verificar horarios. Usalas en vez de responder de memoria. Los datos que
devuelven son la única fuente de verdad sobre precios y horarios.

# Tono
- Cordial salvadoreño: "con gusto", "fíjese que", "¡cómo no!". Trato de "usted".
- Respuestas cortas (1-3 oraciones), un emoji máximo (😊 🫓).

# Reglas del negocio
- Para registrar un pedido necesitás: items, nombre del cliente y sucursal.
  Pedí solo lo que falte. Antes de registrar, confirmá el pedido con el total.
- Si un item no está en el menú, ofrecé lo más parecido que sí esté.

# Qué NO hacés
- Nunca inventés precios ni platillos: consultá el menú.
- No registrés pedidos sin confirmación explícita del cliente.
- No hablés de temas ajenos a la pupusería; redirigí con amabilidad.

# Formato
- Pedidos: items con viñetas y total al final. Sin tablas ni markdown pesado.
"""


class Chatbot:
    """Chatbot con historial y loop agentico de herramientas."""

    def __init__(self, system_prompt: str, model: str = "claude-opus-4-8"):
        self.client = anthropic.Anthropic()
        self.system_prompt = system_prompt
        self.model = model
        self.historial: list[dict] = []

    # ---------- memoria (cap. 2) ----------

    def _recortar_historial(self) -> list[dict]:
        if len(self.historial) <= MAX_TURNOS:
            return self.historial
        recorte = self.historial[-MAX_TURNOS:]
        # No empezar en assistant NI dejar un tool_result huerfano al inicio:
        while recorte and (
            recorte[0]["role"] == "assistant"
            or (isinstance(recorte[0].get("content"), list)
                and any(getattr(b, "type", b.get("type") if isinstance(b, dict) else "")
                        == "tool_result" for b in recorte[0]["content"]))
        ):
            recorte = recorte[1:]
        return recorte

    # ---------- herramientas ----------

    def _ejecutar_tool(self, bloque) -> dict:
        """Ejecuta un bloque tool_use y devuelve el tool_result correspondiente."""
        funcion = IMPLEMENTACIONES.get(bloque.name)
        if funcion is None:
            return {
                "type": "tool_result",
                "tool_use_id": bloque.id,
                "content": f"Herramienta desconocida: {bloque.name}",
                "is_error": True,
            }
        try:
            resultado = funcion(**bloque.input)   # .input ya es un dict
            return {
                "type": "tool_result",
                "tool_use_id": bloque.id,
                "content": resultado,
            }
        except Exception as e:
            # El error viaja al modelo, que puede corregir y reintentar.
            return {
                "type": "tool_result",
                "tool_use_id": bloque.id,
                "content": f"Error al ejecutar {bloque.name}: {e}",
                "is_error": True,
            }

    # ---------- el loop agentico ----------

    def enviar(self, mensaje_usuario: str) -> str:
        self.historial.append({"role": "user", "content": mensaje_usuario})

        for _ in range(MAX_CICLOS_TOOLS):
            response = self.client.messages.create(
                model=self.model,
                max_tokens=1024,
                system=self.system_prompt,
                tools=TOOLS,
                messages=self._recortar_historial(),
            )

            if response.stop_reason != "tool_use":
                # end_turn (o max_tokens/refusal): respuesta final de texto.
                texto = "".join(b.text for b in response.content
                                if b.type == "text")
                self.historial.append({"role": "assistant", "content": texto})
                return texto

            # El modelo pidio herramientas (puede pedir VARIAS en un turno).
            # 1) Guardar el turno assistant COMPLETO, con sus bloques tool_use:
            self.historial.append({"role": "assistant",
                                   "content": response.content})

            # 2) Ejecutar cada tool_use y juntar todos los resultados:
            resultados = [
                self._ejecutar_tool(bloque)
                for bloque in response.content
                if bloque.type == "tool_use"
            ]

            # 3) Devolverlos en UN solo turno user:
            self.historial.append({"role": "user", "content": resultados})
            # ... y el for vuelve a llamar a la API con todo el contexto.

        # Tope de ciclos alcanzado: cortar con elegancia.
        texto = ("Disculpe, se me complicó procesar eso 😅 "
                 "¿Me lo repite de otra forma?")
        self.historial.append({"role": "assistant", "content": texto})
        return texto


def main():
    bot = Chatbot(SYSTEM_PROMPT)
    print("🫓 Esquinita v3 (con herramientas) — 'salir' para terminar.\n")
    while True:
        entrada = input("Vos: ").strip()
        if entrada.lower() in ("salir", "exit", "quit"):
            print("¡Que le vaya bien!")
            break
        if not entrada:
            continue
        print(f"\nBot: {bot.enviar(entrada)}\n")


if __name__ == "__main__":
    main()

Probálo con una conversación de pedido completa:

Vos: ¿A cuánto están las de loroco?
Bot: ¡Con gusto! La pupusa de loroco con queso está a 0.90 😊

Vos: Dame 4 de esas y 2 horchatas. Soy Beatriz, paso por la del centro.
Bot: ¡Cómo no, Beatriz! Su pedido sería:
     • 4 pupusas de loroco con queso — 3.60
     • 2 horchatas — 2.00
     Total: 5.60 dólares, para recoger en la sucursal Centro. ¿Se lo confirmo?

Vos: Sí, confirmado.
Bot: ¡Listo! Su pedido quedó registrado con el número 1. 🫓

Detrás de escena, ese segundo mensaje disparó dos herramientas (consultar_menu para verificar el loroco y calcular_pedido para el total), y el tercero disparó registrar_pedido — que escribió de verdad en pedidos.json. Abrí el archivo y comprobalo.

user: "¿a cuánto las de queso?"
assistant: [tool_use id=abc, consultar_menu, ...]      ← ESTE turno se te olvida
user: [tool_result tool_use_id=abc, "{...precios...}"]

3.5 Probar las herramientas sin gastar tokens

Las implementaciones son funciones Python puras: se testean sin tocar la API (gratis y en milisegundos). Creá test_herramientas.py:

"""Tests de las herramientas — sin llamar a la API, sin gastar un centavo."""
import json

from herramientas import calcular_pedido, consultar_menu, verificar_horario


def test_calculo_simple():
    r = json.loads(calcular_pedido([{"nombre": "queso", "cantidad": 3},
                                    {"nombre": "horchata", "cantidad": 2}]))
    assert r["total"] == 4.25
    assert r["items_no_encontrados"] == []


def test_item_inexistente():
    r = json.loads(calcular_pedido([{"nombre": "pizza", "cantidad": 1}]))
    assert r["items_no_encontrados"] == ["pizza"]
    assert r["total"] == 0


def test_menu_por_categoria():
    r = json.loads(consultar_menu("bebidas"))
    assert "horchata" in r["bebidas"]


def test_horario_estructura():
    r = json.loads(verificar_horario("centro"))
    assert r["sucursal"] == "centro"
    assert isinstance(r["abierta_ahora"], bool)


if __name__ == "__main__":
    test_calculo_simple()
    test_item_inexistente()
    test_menu_por_categoria()
    test_horario_estructura()
    print("✅ Todos los tests pasaron.")

Esta separación — schemas y loop por un lado, lógica de negocio testeable por el otro — es el diseño que vas a ver en cualquier base de código seria de agentes.

Resumen visual

Estado del proyecto — R1 (menú sin inventar) ✅, R2 (totales exactos) ✅, R3 (registrar pedidos) ✅, R4 (horarios) ✅, más R6 y R7 del capítulo anterior. Falta que el bot conozca las políticas del negocio (R5) — ¿qué pasa si preguntan por entregas a domicilio o cómo encargar 200 pupusas para un cumpleaños? Eso es el capítulo 4: RAG.

Ejercicios

if DEBUG:
    for b in response.content:
        if b.type == "tool_use":
            print(f"  🔧 {b.name}({json.dumps(b.input, ensure_ascii=False)})")
for r in resultados:
    if DEBUG:
        print(f"  ↩️  {str(r['content'])[:80]}{' [ERROR]' if r.get('is_error') else ''}")

{
    "name": "consultar_pedido",
    "description": (
        "Devuelve los datos de un pedido ya registrado (items, total, sucursal, "
        "cliente) a partir de su número. Usala cuando el cliente pregunte por "
        "el estado o contenido de un pedido existente. NO sirve para crear ni "
        "modificar pedidos."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "numero_pedido": {"type": "integer",
                              "description": "Número de pedido que recibió el cliente."},
        },
        "required": ["numero_pedido"],
    },
}

def consultar_pedido(numero_pedido: int) -> str:
    from pathlib import Path
    ruta = Path(datos.ARCHIVO_PEDIDOS)
    if not ruta.exists():
        raise ValueError("Todavía no hay pedidos registrados.")
    pedidos = json.loads(ruta.read_text(encoding="utf-8"))
    for p in pedidos:
        if p["numero"] == numero_pedido:
            return json.dumps(p, ensure_ascii=False)
    raise ValueError(f"No existe el pedido número {numero_pedido}.")

self.historial.append({"role": "assistant", "content": response.content})
for bloque in response.content:
    if bloque.type == "tool_use":
        resultado = self._ejecutar_tool(bloque)
        self.historial.append({"role": "user", "content": [resultado]})

Para profundizar

• Tool use en la documentación oficial — platform.claude.com/docs, sección Tool use: el contrato completo, tool_choice (forzar o prohibir herramientas), tool use con streaming y herramientas del lado del servidor.
• JSON Schema — json-schema.org: la especificación de input_schema. Con type, enum, required y description cubrís el 95% de los casos reales.
• Capítulo 6 del libro de IA — LLMs y transformers, sección de agentes: el contexto conceptual de los loops agénticos.
• Anthropic Cookbook — github.com/anthropics/anthropic-cookbook: notebooks oficiales con patrones avanzados de tool use (orquestación, herramientas paralelas, validación).