Saltar a contenido

Herramientas

Una herramienta es una función de Python que el modelo puede pedir que se ejecute. El modelo no la ve por dentro: ve su nombre, su descripción y qué argumentos espera. Con eso decide cuándo usarla y con qué valores, y con lo que devuelve escribe la respuesta.

Las herramientas son la forma de que el asistente sepa algo de tu empresa. Sin ellas, contesta con lo que sabe el modelo; con ellas, con tus datos.

Dónde van

agente/herramientas/
├── __init__.py     la lista `tools`: las que recibe el agente
├── toolfuncs.py    las funciones
└── schemas.py      sus argumentos, cuando se declaran con Pydantic

Una herramienta existe para el agente cuando está en la lista de __init__.py:

agente/herramientas/__init__.py
from .toolfuncs import *

tools = [
    suma,
    contar_mis_conversaciones,
    dias_entre,          # ← la nueva
]

Al reiniciar la API (tai-chat dev recarga solo al guardar), el modelo ya la tiene.

Si son muchas, toolfuncs.py puede ser un paquete con un módulo por tema —averias.py, costes.py— y __init__.py reunir las de todos.

La más sencilla

agente/herramientas/toolfuncs.py
from datetime import date
from langchain_core.tools import tool


@tool
async def dias_entre(desde: date, hasta: date) -> int:
    """Cuántos días naturales hay entre dos fechas, contando las dos."""
    return (hasta - desde).days + 1

Con esto el modelo recibe:

De dónde sale Aquí
El nombre El de la función dias_entre
La descripción El docstring «Cuántos días naturales hay entre dos fechas, contando las dos.»
Los argumentos Las anotaciones de tipo desde y hasta, fechas en ISO

Cuando un usuario pregunta «¿cuántos días van del 3 de marzo al 18 de abril?», el modelo pide dias_entre(desde="2026-03-03", hasta="2026-04-18"), LangChain convierte los argumentos a date, la función devuelve 47, y el modelo contesta con ese número.

La descripción es para el modelo

Es lo único que tiene para decidir si la usa. Di qué devuelve y cuándo conviene usarla, no cómo está hecha. Si dos herramientas se parecen, di en qué se diferencian. Una buena descripción ahorra más errores que un buen prompt.

Argumentos bien descritos

Las anotaciones dicen el tipo, pero no qué significa cada argumento. Hay dos formas de contarlo.

Con el docstring

Con parse_docstring=True, LangChain lee la sección Args: del docstring (estilo Google) y la pone como descripción de cada argumento:

from typing import Literal


@tool(parse_docstring=True)
async def convertir(importe: float, de: Literal["EUR", "USD", "GBP"], a: Literal["EUR", "USD", "GBP"]) -> float:
    """Convierte un importe entre monedas con el cambio del día.

    Args:
        importe: La cantidad a convertir.
        de: La moneda en la que está el importe.
        a: La moneda a la que se convierte.
    """
    return round(importe * await cambio(de, a), 2)

Un Literal se convierte en una lista cerrada de valores: el modelo no puede inventarse una moneda.

Con un modelo de Pydantic

Para argumentos con restricciones, valores por defecto u opcionales, mejor un modelo de Pydantic en schemas.py:

agente/herramientas/schemas.py
from datetime import date
from typing import Literal, Optional
from pydantic import BaseModel, Field


class BuscarAveriasParams(BaseModel):
    estado: Literal["abierta", "en_curso", "cerrada"] = Field(
        "abierta", description="En qué estado están las averías que se buscan"
    )
    linea: Optional[str] = Field(
        None, description="La línea de producción, por ejemplo 'L2'. Sin ella, todas"
    )
    desde: Optional[date] = Field(
        None, description="Solo las abiertas a partir de este día"
    )
    limite: int = Field(
        20, ge=1, le=50, description="Cuántas devolver como mucho, las más recientes primero"
    )
agente/herramientas/averias.py
@tool(args_schema=BuscarAveriasParams)
async def buscar_averias(
    runtime: ToolRuntime[Contexto],
    estado: str = "abierta",
    linea: Optional[str] = None,
    desde: Optional[date] = None,
    limite: int = 20,
) -> dict:
    """Busca averías por estado, línea y fecha. Devuelve un resumen de cada una: para el
    detalle completo de una avería, usa detalle_averia con su id."""
    ...  # el cuerpo, en «Herramientas que leen datos»

Las descripciones de los campos, sus valores posibles, sus mínimos y máximos y sus valores por defecto llegan al modelo. runtime no está en el schema ni lo ve el modelo: lo pone LangChain al ejecutarla, y es por donde la herramienta sabe quién pregunta (ver más abajo).

Si el modelo se equivoca en un argumento

Si pide limite=500 o un estado que no existe, la validación falla antes de ejecutar la función, y el error vuelve al modelo como resultado de la herramienta. El modelo lo lee y suele corregirse en la siguiente vuelta. No hace falta validar a mano lo que ya dice el schema.

Qué devolver

Lo que devuelve la herramienta se convierte en texto y se le da al modelo. Vale cualquier cosa serializable:

Devolver Cuándo
Un str Una frase hecha: «Juan tiene 4 conversaciones»
Un número Un dato suelto
Un dict o una list[dict] Filas, registros, resúmenes: el modelo entiende bien el JSON
@tool
async def resumen_linea(linea: str) -> dict:
    """Cuántas averías hay en una línea, por estado, y el coste de las cerradas este año."""
    return {
        "linea": linea,
        "abiertas": 3,
        "en_curso": 1,
        "cerradas_este_año": 27,
        "coste_cerradas_eur": 18430.5,
    }

Tres reglas que ahorran tokens y errores:

  1. Devuelve solo lo que el modelo necesita. Cada carácter del resultado son tokens de entrada en esta llamada y en las siguientes, porque el resultado se queda en la memoria de la conversación. Un resumen con los campos útiles, no la fila entera con sus fechas de auditoría.
  2. Acota cuántas filas. Pon siempre un límite, y di en la descripción que lo hay. Si hay más, dilo en el resultado ("total": 312, "devueltas": 20) para que el modelo no lo tome por todo.
  3. Usa nombres que se entiendan. coste_eur mejor que c_tot: el modelo lee las claves.

El resultado también se guarda en la tabla tool_call, y quien tenga app-lab lo ve en el front debajo de la respuesta: es lo primero que hay que mirar cuando el asistente contesta algo raro.

Leer datos de la base de datos

Una herramienta que lee datos lo hace en nombre del usuario que pregunta, con su permiso y sus reglas de fila. Es lo bastante importante como para tener su página: Herramientas que leen datos. El patrón, en corto:

from langchain.tools import ToolRuntime
from api.database.mantenimiento import AveriaAsyncDAO
from ..contexto import Contexto


@tool
async def mis_averias_abiertas(runtime: ToolRuntime[Contexto]) -> list[dict]:
    """Las averías abiertas de las que es responsable el usuario."""
    runtime.context.exigir("read", "averia")                  # su permiso
    filas = await AveriaAsyncDAO.find_many(
        estado="abierta",
        rls=runtime.context.reglas("mantenimiento"),           # sus reglas de fila
        limit=20,
    )
    return [{"id": f.id, "maquina": f.maquina_id, "descripcion": f.descripcion} for f in filas]

runtime no lo ve el modelo: LangChain lo inyecta al ejecutar la herramienta.

Cuando la respuesta no está en columnas sino escrita en manuales, procedimientos o normas, la herramienta busca por significado: Buscar en documentos.

Llamar a otro servicio

Una herramienta puede llamar a cualquier cosa: una API interna, el ERP, un servicio externo. Con httpx, asíncrono:

import os
import httpx


@tool(parse_docstring=True)
async def stock_repuesto(referencia: str) -> dict:
    """Cuántas unidades quedan de un repuesto en el almacén, y dónde están.

    Args:
        referencia: La referencia del repuesto, por ejemplo 'RD-2210'.
    """
    async with httpx.AsyncClient(timeout=10) as http:
        r = await http.get(
            f"{os.environ['ERP_URL']}/stock/{referencia}",
            headers={"Authorization": f"Bearer {os.environ['ERP_TOKEN']}"},
        )
    if r.status_code == 404:
        raise ToolException(f"No hay ningún repuesto con la referencia {referencia}")
    r.raise_for_status()
    datos = r.json()
    return {"referencia": referencia, "unidades": datos["qty"], "ubicacion": datos["bin"]}

stock_repuesto.handle_tool_error = True
  • Los secretos, de variables de entorno. Nunca en el código, y nunca en lo que se devuelve al modelo: el resultado se guarda y se enseña.
  • Siempre con timeout. Mientras la herramienta espera, el usuario mira la burbuja escribiendo.
  • Una dependencia nueva va en el proyecto de la API, no en tai-chat: cd chatbot/api && poetry add httpx.

Los errores

Una herramienta puede fallar de dos maneras, y conviene distinguirlas.

Un error que el modelo puede resolver —no existe esa referencia, la fecha está fuera de rango, esa máquina no tiene averías— se lanza como ToolException, y la herramienta se marca con handle_tool_error = True:

from langchain_core.tools import ToolException


@tool
async def detalle_averia(averia_id: int) -> dict:
    """El detalle completo de una avería: la máquina, quién la abrió, las intervenciones y el coste."""
    averia = await leer_averia(averia_id)     # la consulta, en «Herramientas que leen datos»
    if averia is None:
        raise ToolException(f"No hay ninguna avería con el id {averia_id}")
    return averia

detalle_averia.handle_tool_error = True

El mensaje de la excepción le llega al modelo como resultado de la herramienta, marcado como error. El modelo lo lee y decide: prueba con otro valor, usa otra herramienta, o se lo cuenta al usuario.

Un error que no es de la conversación —la base de datos no contesta, un fallo de programación— se deja subir. La respuesta se corta, el usuario ve que no se pudo completar, y la traza queda en el log. Tragárselo y devolverle algo al modelo solo serviría para que se inventara una respuesta.

Lanzar Con handle_tool_error Qué pasa
ToolException True El modelo recibe el mensaje y sigue
ToolException sin poner La respuesta se corta, como con cualquier otra excepción
SinPermiso (con runtime.context.exigir) no hace falta El modelo recibe «No tienes permiso para…» y sigue. Lo hace SinPermisoMiddleware
Cualquier otra excepción — La respuesta se corta y no se guarda; lo gastado hasta ahí, sí. El usuario ve «No se pudo completar la respuesta», y el log, la excepción
Argumentos que no cumplen el schema — El modelo recibe el error de validación y sigue

En el registro de la respuesta (app-lab), una herramienta que devolvió un error aparece marcada como fallida, con el mensaje que recibió el modelo.

Lo que va en el mensaje lo lee el modelo, y puede repetirlo

No pongas en un ToolException nada que el usuario no deba ver: ni datos de otros, ni rutas internas, ni la consulta SQL.

Asíncronas o no

Mejor async def: el agente es asíncrono, y los DAOs que genera tai-api también. Una herramienta síncrona funciona —LangChain la ejecuta en un hilo aparte—, y es lo que toca si usa una librería que bloquea. Lo que no se puede es llamar a algo bloqueante (requests, time.sleep, un driver síncrono) dentro de una async def: pararía la API entera mientras espera.

Herramientas según quién pregunta

Hay dos niveles, y se complementan:

Dónde Qué consigue
Que el modelo no la vea ToolPermissionMiddleware.RULES El modelo de un usuario sin el permiso ni sabe que existe. Ahorra tokens y errores
Que no lea lo que no debe Dentro de la herramienta: exigir y reglas Es lo que protege los datos, aunque el modelo la pida

El primero está en El agente; el segundo, en Herramientas que leen datos. Con el segundo basta para que sea seguro; el primero hace que el asistente sea más útil para cada uno.

Probar una herramienta

Una herramienta que no usa runtime se puede llamar directamente:

import asyncio
from api.routers.custom.assistant.agente.herramientas.toolfuncs import dias_entre

print(asyncio.run(dias_entre.ainvoke({"desde": "2026-03-03", "hasta": "2026-04-18"})))  # 47

Desde chatbot/api/, con el .env exportado. Para ver cómo la usa el modelo, lo más rápido es el chat con el permiso app-lab: debajo de cada respuesta aparece qué herramienta pidió, con qué argumentos y qué le devolvió.

Cuando una herramienta se queda corta

Si una tarea necesita varias consultas que dependen unas de otras —buscar, mirar el detalle de las que encajan, cruzar con otra tabla, resumir—, hay dos caminos:

  • Darle al agente principal las herramientas sueltas y dejar que las encadene. Es lo más simple, pero cada paso gasta una iteración y llena su memoria de resultados intermedios.
  • Una herramienta que construye su propio agente, con su prompt y sus herramientas, que hace todo el trabajo y devuelve solo la conclusión. Es lo que explica Sub-agentes.