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:
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¶
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:
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"
)
@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:
- 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.
- 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. - Usa nombres que se entiendan.
coste_eurmejor quec_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.