Herramientas de chat

Chat puede permitir que el modelo llame a herramientas. Con ellas activadas, un turno ejecuta un bucle nativo de varias rondas: el modelo solicita una herramienta, Libre WebUI la ejecuta con la identidad y permisos del usuario, devuelve el resultado al modelo y continúa hasta que responda. Hay hasta ocho rondas por turno y ocho llamadas por ronda. Detener cancela la llamada al modelo, cualquier herramienta en curso y cualquier aprobación pendiente.

Las llamadas se registran como eventos normalizados (chat.tool-call.v1, chat.tool-result.v1, chat.approval.v1) que fluyen igual por el WebSocket privado y el flujo duradero; una recarga o reconexión reproduce el mismo estado. El turno terminado almacena sus llamadas y vistas previas acotadas de los resultados en el mensaje del asistente.

Activar herramientas

Están desactivadas de forma predeterminada. Un administrador las habilita en Configuración → Gestión de usuarios (solo administradores o todos); cada turno las activa mediante la llave inglesa del editor, que abre un selector con un interruptor general y una casilla por herramienta integrada y servidor registrado. El turno utiliza exactamente lo elegido. El selector puede restringir las vinculaciones de un perfil, nunca ampliarlas. Los chats privados (de incógnito) no ofrecen herramientas: una llamada es una acción exterior que puede dejar aprobaciones y registros de auditoría.

Un perfil de asistente (persona) puede limitar lo ofrecido: servidores vinculados, un subconjunto de herramientas integradas, habilidades y colecciones de conocimiento restringen lo que ve el modelo en sus sesiones.

Herramientas integradas

Chat incluye trece herramientas propias (todas de solo lectura salvo las que modifican notas y calendarios, sujetas a aprobación):

• web_search: motor de búsqueda configurado por el administrador, respetando el modo de acceso.
• search_documents: búsqueda híbrida en documentos y colecciones del usuario, incluidas las compartidas (las vinculaciones pueden limitar las colecciones); cada pasaje cita su fragmento y ubicación.
• list_documents: enumera documentos del ámbito del chat con ID, tipo y tamaño para que el modelo decida qué leer.
• read_document: lee una ventana acotada de un documento por ID y desplazamiento, con su ubicación, para recorrer archivos que la recuperación no resuelve sola.
• load_skill: carga instrucciones completas de una habilidad por slug; su descripción contiene el manifiesto de habilidades activas, que permanecen diferidas hasta necesitarlas. Si incluye archivos, termina con su inventario.
• read_skill_file: lee un archivo auxiliar de una habilidad por slug y ruta relativa, para no gastar contexto hasta abrir una referencia grande.
• list_notes: enumera notas propias y compartidas con sus ID.
• read_note: lee todo el contenido de una nota por ID.
• create_note: crea una nota (efecto secundario, requiere aprobación).
• update_note: sustituye el contenido y conserva el estado anterior como revisión restaurable, por lo que una edición del modelo siempre es reversible (requiere aprobación).
• list_calendar_events: enumera eventos propios y compartidos en un intervalo de milisegundos desde la época Unix.
• create_calendar_event: crea un evento (requiere aprobación).
• delete_calendar_event: elimina un evento por ID (requiere aprobación).

Servidores de herramientas

Los administradores registran servidores externos en Ajustes → Herramientas (las plantillas iniciales rellenan el formulario, incluida una API pública de demostración segura):

• OpenAPI: se obtiene una especificación JSON OpenAPI 3.x una vez y se fija con un resumen SHA-256. Cada operación se convierte en herramienta; GET es de solo lectura y todo lo demás tiene efecto secundario hasta que el administrador anule la clasificación. La ejecución reconstruye la llamada desde la operación fijada; los argumentos del modelo nunca eligen el destino.
• MCP (Streamable HTTP): la lista del servidor se obtiene mediante JSON-RPC y se fija igual. annotations.readOnlyHint marca el modo de solo lectura. Los servidores MCP stdio no son compatibles deliberadamente: nunca se ejecutan procesos externos dentro del proceso web.

Un inventario modificado solo entra en vigor cuando un administrador actualiza el servidor, lo que avanza la revisión fijada y conserva las anulaciones. La disponibilidad puede ser solo para administradores, para todos o mediante permisos a usuarios y grupos del modelo compartido.

Credenciales

Los servidores autenticados utilizan credenciales por usuario (token Bearer o cabecera con nombre). Cada secreto se cifra con datos autenticados adicionales que lo vinculan al usuario y servidor exactos, se introduce en Ajustes → Herramientas y nunca se comparte entre cuentas.

Política de salida

Cada solicitud resuelve su propio destino, rechaza espacios privados, de bucle invertido y metadatos, y fija la conexión a la dirección resuelta para impedir redirecciones por rebinding de DNS. Se rechazan las redirecciones HTTP. Las respuestas tienen límite de tamaño y cada llamada una espera estricta. TOOLS_PRIVATE_NETWORK_ALLOWLIST permite nombres internos exactos (separados por comas), que siguen fijados y acotados. La salida vuelve al modelo como texto no fiable.

Aprobaciones

Las herramientas de lectura se ejecutan sin preguntar. Una herramienta con efectos detiene el turno y pregunta: permitir una vez, para este chat, siempre para esta herramienta en este servidor, o denegar. Las decisiones son duraderas; «siempre» sobrevive a reinicios y puede revocarse en Ajustes → Herramientas. Una solicitud pendiente caduca a los dos minutos y el modelo la ve como denegada. La denegación o caducidad nunca ejecutan la llamada. Toda decisión y llamada deja un evento de seguridad censurado.

Ejemplos

Activa primero la llave inglesa del editor; cada ejemplo es un mensaje normal.

web_search: buscar algo

¿Qué cambió en la última versión de SQLite? Busca en la web antes de responder.

El modelo llama a web_search con una consulta como {"query": "SQLite latest release changelog"}; la tarjeta muestra los fragmentos recibidos y la respuesta cita lo encontrado. Requiere que la búsqueda web esté configurada y permitida.

search_documents: consultar tus archivos

Sube un PDF o añade documentos a una colección y pregunta:

Busca la cláusula de rescisión en mis documentos y cítala exactamente.

El modelo llama a search_documents con {"query": "termination clause"} y recibe pasajes etiquetados con el documento fuente para citarlos y atribuirlos.

load_skill: aplicar una habilidad guardada

Crea una habilidad en Ajustes → Habilidades (por ejemplo, $release-notes, que explica cómo escribir notas de versión) y pide:

Redacta notas de versión de este diff usando $release-notes.

El modelo ve la habilidad en su manifiesto, llama a load_skill {"slug": "release-notes"} para cargar las instrucciones y las sigue. Escribir $ autocompleta los slugs.

Un servidor OpenAPI: por ejemplo, una API meteorológica

1. Ajustes → Herramientas → Registrar servidor: nombre Weather, tipo OpenAPI, URL base https://api.example-weather.dev, URL de especificación https://api.example-weather.dev/openapi.json, autenticación bearer.

2. La especificación se fija y sus operaciones aparecen como herramientas, por ejemplo getForecast (GET, lectura) y createAlert (POST, efecto secundario).

3. Cada usuario guarda su propia clave de API en la tarjeta.

4. En el chat:

   ¿Qué tiempo hará en Montreal este fin de semana?

   El modelo llama a weather__getForecast {"city": "Montreal"} y se ejecuta inmediatamente; la lectura nunca pregunta.

   Avísame si baja de -20 esta noche.

   weather__createAlert tiene efectos, así que el turno muestra una tarjeta: Permitir una vez, Permitir para este chat, Permitir siempre o Denegar. No se envía nada hasta elegir.

Un servidor MCP: por ejemplo, un gestor de incidencias

1. Ajustes → Herramientas → Registrar servidor: nombre Issues, tipo MCP, URL base https://mcp.example-tracker.dev/mcp, autenticación header con cabecera X-Api-Key.

2. Se fija su lista; las herramientas marcadas como lectura (como search_issues) se ejecutan libremente y las demás (como create_issue) preguntan.

3. En el chat:

   Busca incidencias abiertas que mencionen "database lock" y crea una nueva que resuma el patrón.

   issues__search_issues se ejecuta de inmediato; issues__create_issue muestra los argumentos exactos para que puedas leer lo que se enviará antes de permitirlo.

Variables de entorno

Variable	Efecto
TOOLS_ACCESS_MODE	Fija la función en admins o all-users y bloquea el interruptor del administrador.
TOOLS_PRIVATE_NETWORK_ALLOWLIST	Nombres exactos que pueden resolverse a direcciones privadas (lista separada por comas).

Límites

• Las llamadas se ejecutan en WebSocket (se excluye deliberadamente el transporte privado) y en la ruta duradera de chats guardados. El endpoint REST antiguo de streaming no ejecuta el bucle.
• Los agentes de Work llaman a los mismos servidores por la misma pasarela: solo en ejecuciones con red, los servidores sin credenciales se filtran al ofrecerlos y las herramientas con efectos quedan sujetas a las aprobaciones de Work.
• Los modelos Gemini y de CLI de agentes no reciben herramientas; sí las reciben Ollama y proveedores compatibles con OpenAI, Responses API y Anthropic.
• Los servidores MCP se autentican con credenciales estáticas por usuario; todavía no se puede registrar uno que solo admita OAuth interactivo.