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 → Acceso y políticas → Acceso a herramientas (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.

El interruptor Acceso a herramientas guarda de inmediato. Haz clic en él o usa Tab para enfocarlo y Space para cambiarlo. Cambiar el acceso mantiene la ventana de ajustes y su posición de desplazamiento.

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.

OAuth interactivo (MCP)

Un servidor MCP también puede identificar a cada persona por sí misma. Regístralo con el modo de autenticación OAuth interactivo y Libre WebUI lee el desafío WWW-Authenticate con el que responde el servidor, lo sigue hasta los metadatos del recurso protegido, luego hasta los metadatos del servidor de autorización, y registra un cliente dinámicamente (RFC 7591) cuando el servidor de autorización ofrece registro. Los proveedores que no registran clientes automáticamente toman un ID de cliente proporcionado por el administrador, y un secreto opcional, en el formulario de registro; el secreto se cifra junto con los endpoints descubiertos.

Cada persona pulsa entonces Conectar en la tarjeta del servidor y es redirigida al proveedor. El flujo usa PKCE (S256) con estado CSRF y el verificador PKCE guardado en una cookie HttpOnly limitada a ese único servidor. La devolución de llamada intercambia el código en el servidor, guarda los tokens cifrados con la misma vinculación de usuario y servidor que un secreto estático, y devuelve el navegador a la app con un indicador de estado: los tokens de acceso y de actualización nunca llegan a la página. Los tokens de acceso se renuevan automáticamente un minuto antes de caducar, una vez por persona y servidor aunque compitan varias llamadas a herramientas. Cuando no es posible renovar, la llamada a la herramienta vuelve pidiendo reconectar en vez de fallar de forma anónima. Desconectar elimina los tokens de esa persona y deja el registro intacto; eliminar el servidor también olvida la configuración descubierta.

Un servidor que rechaza un listado de herramientas sin autenticar igualmente queda registrado: su inventario se fija en la primera conexión correcta (y en cualquier actualización del administrador), de modo que nada se ofrece a un modelo antes de conocerse.

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.

Exa MCP: buscar y recuperar páginas web

En Configuración → Herramientas → Empieza con una plantilla, elige Exa para prerrellenar un registro MCP con:

https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa

La URL selecciona web_search_exa y web_fetch_exa mediante el parámetro de selección de herramientas de Exa. La plantilla no usa autenticación y limita el acceso a administradores de forma predeterminada. Revisa el formulario y elige Guardar para conectar y fijar el inventario de herramientas. Abrir o cancelar la plantilla no contacta con Exa. Las consultas de búsqueda y las URL solicitadas se envían a Exa cuando se ejecutan estas herramientas.

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.
• Las menciones a @model en canales ejecutan el mismo bucle contra el catálogo del miembro que menciona, con una diferencia: no hay nadie a quien preguntar, así que una herramienta con efectos secundarios sin una aprobación permanente se rechaza de inmediato en vez de esperar. Las herramientas de solo lectura se ejecutan con normalidad.
• 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.
• El OAuth interactivo es exclusivo de MCP: un servidor OpenAPI sigue usando una credencial estática por usuario. El flujo es la concesión de código de autorización con PKCE; los flujos de código de dispositivo y de credenciales de cliente no se ofrecen, y un servidor de autorización que no publica metadatos (o que no tiene endpoint de registro ni ID de cliente proporcionado por el administrador) no se puede conectar.
• Los endpoints de OAuth descubiertos deben ser https; se acepta http simple solo para loopback, para un proveedor que se ejecuta en la misma máquina durante el desarrollo.
• El URI de redirección se deriva de BASE_URL (o del primer CORS_ORIGIN), así que ese valor debe ser la dirección que el navegador realmente alcanza y debe registrarse con los proveedores que fijan URIs de redirección.