Strumenti della chat

La Chat può permettere al modello di chiamare strumenti. Un turno abilitato esegue un loop nativo multi-round: il modello richiede, Libre WebUI esegue con identità e permessi dell'utente, il risultato torna al modello e il loop continua fino alla risposta — massimo otto round e otto chiamate per round. Stop annulla modello, strumento in corso e approvazione in attesa.

Le chiamate sono eventi normalizzati (chat.tool-call.v1, chat.tool-result.v1, chat.approval.v1) identici sul WebSocket privato e sul flusso duraturo, quindi refresh o riconnessione riproducono lo stato. Il turno concluso salva le chiamate, con anteprime limitate, nel messaggio.

Abilitare gli strumenti

Sono disattivati per impostazione predefinita. Un amministratore li apre in Impostazioni → Gestione utenti → Accesso e criteri → Accesso agli strumenti (solo admin o tutti). Ogni turno opta tramite la chiave inglese, che apre un selettore generale e una casella per ogni strumento/server, usando esattamente quelli scelti. Il selettore può restringere un profilo, mai ampliare. Le chat private non li offrono: un'azione esterna può lasciare approvazioni e audit.

L'interruttore Accesso agli strumenti salva immediatamente. Fai clic su di esso, oppure usa Tab per portarlo a fuoco e Space per commutarlo. La modifica dell'accesso mantiene la finestra Impostazioni e la sua posizione di scorrimento.

Un profilo può limitare server, strumenti integrati, abilità e raccolte visibili.

Strumenti integrati

Tredici strumenti sono inclusi; tutti sono in sola lettura tranne modifiche a note e calendario, soggette ad approvazione:

• web_search — motore configurato dall'amministratore e relativo accesso.
• search_documents — ricerca ibrida su documenti e raccolte, anche condivise, con citazione.
• list_documents — elenca ID, tipi e dimensioni nell'ambito.
• read_document — legge una finestra limitata per ID e offset con provenienza.
• load_skill — carica istruzioni complete per slug; il manifesto rimane lazy e l'inventario dei file è aggiunto.
• read_skill_file — legge un file associato per slug e percorso relativo.
• list_notes — elenca Note proprie e condivise.
• read_note — legge una Nota.
• create_note — crea (effetto collaterale, approvazione).
• update_note — sostituisce mantenendo una revisione ripristinabile (approvazione).
• list_calendar_events — elenca eventi in un intervallo epoch-millisecond.
• create_calendar_event — crea evento (approvazione).
• delete_calendar_event — elimina evento (approvazione).

Server di strumenti

Gli amministratori li registrano in Impostazioni → Strumenti:

• OpenAPI: una specifica JSON OpenAPI 3.x viene scaricata una volta e fissata con SHA-256. Ogni operazione diventa uno strumento; GET è sola lettura, il resto effetto collaterale finché non sostituito. La chiamata viene ricostruita dall'operazione fissata, quindi gli argomenti non scelgono la destinazione.
• MCP (Streamable HTTP): la lista viene ottenuta tramite JSON-RPC e fissata. annotations.readOnlyHint indica sola lettura. MCP stdio non è supportato deliberatamente: processi esterni non girano nel processo web.

Un inventario cambiato entra in vigore solo dopo refresh admin, mantenendo le sostituzioni. La disponibilità può essere admin, tutti o basata su autorizzazioni a utenti/gruppi.

Credenziali

Server autenticati usano credenziali per utente (Bearer o header). Ogni segreto è cifrato con dati autenticati che lo legano a utente e server esatti, inserito in Impostazioni → Strumenti e mai condiviso.

OAuth interattivo (MCP)

Un server MCP può anche autenticare ogni persona singolarmente. Registralo con la modalità di autenticazione OAuth interattivo: Libre WebUI legge la sfida WWW-Authenticate restituita dal server, la segue fino ai metadati della risorsa protetta, poi ai metadati del server di autorizzazione, e registra un client dinamicamente (RFC 7591) quando il server di autorizzazione offre la registrazione. I provider che non registrano client automaticamente richiedono un ID client fornito dall'amministratore (e un segreto facoltativo) nel modulo di registrazione; il segreto viene cifrato insieme agli endpoint scoperti.

Ogni persona preme Connetti sulla scheda del server e viene reindirizzata al provider. Il flusso usa PKCE (S256) con stato CSRF e il verificatore PKCE conservato in un cookie HttpOnly limitato a quel singolo server. Il callback scambia il codice sul server, memorizza i token cifrati con lo stesso legame utente-e-server usato per un segreto statico e rimanda il browser all'app con un flag di stato — i token di accesso e di refresh non raggiungono mai la pagina. I token di accesso si rinnovano automaticamente un minuto prima della scadenza, una sola volta per persona e server anche quando più chiamate a strumenti corrono in parallelo. Quando un rinnovo non è possibile, la chiamata allo strumento torna chiedendo di riconnettersi anziché fallire in modo anonimo. Disconnetti rimuove i token di quella persona e lascia la registrazione al suo posto; eliminare il server dimentica anche la configurazione scoperta.

Un server che rifiuta un elenco strumenti non autenticato viene comunque registrato: il suo inventario è fissato alla prima connessione riuscita (e a ogni refresh dell'amministratore), così non viene offerto nulla a un modello prima di conoscerlo.

Policy di uscita

Ogni richiesta risolve la destinazione, rifiuta reti private, loopback e metadata e fissa la connessione all'indirizzo per impedire DNS rebind. Rifiuta redirect, limita risposta e timeout. Host interni esatti possono essere consentiti con TOOLS_PRIVATE_NETWORK_ALLOWLIST; restano fissati e limitati. L'output rientra come testo non affidabile.

Approvazioni

La sola lettura esegue senza chiedere. Un effetto collaterale pausa e offre: una volta, in questa chat, sempre per questo strumento/server o nega. Le decisioni sono durature; "sempre" sopravvive e può essere revocato. La richiesta scade in due minuti come rifiuto. Rifiuti e timeout non eseguono. Ogni decisione/chiamata lascia audit oscurato.

Esempi

Attiva prima la chiave inglese.

web_search

Cosa è cambiato nell'ultima versione di SQLite? Cerca sul web prima di rispondere.

Il modello chiama web_search con {"query": "SQLite latest release changelog"}; la scheda mostra gli estratti e la risposta cita le fonti.

search_documents

Cerca nei miei documenti la clausola di risoluzione e citala esattamente.

Chiama {"query": "termination clause"} e riceve passaggi con origine.

load_skill

Crea $release-notes in Impostazioni → Abilità, poi:

Scrivi le note di rilascio per questo diff usando $release-notes.

Il modello chiama load_skill {"slug": "release-notes"}. Digitare $ completa gli slug.

Server OpenAPI — meteo

1. Registra nome Weather, tipo OpenAPI, base https://api.example-weather.dev, specifica https://api.example-weather.dev/openapi.json, auth bearer.
2. Compaiono getForecast (GET) e createAlert (POST).
3. Ogni utente salva la propria chiave.
4. Il modello chiama weather__getForecast {"city": "Montreal"} senza chiedere; weather__createAlert mostra Consenti una volta, in questa chat, sempre o Nega.

Exa MCP — cercare e recuperare dal web

In Impostazioni → Strumenti → Parti da un modello, scegli Exa per precompilare una registrazione MCP con:

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

L'URL seleziona web_search_exa e web_fetch_exa tramite il parametro di selezione degli strumenti di Exa. Il modello non usa autenticazione e per impostazione predefinita limita l'accesso agli amministratori. Rivedi il modulo e scegli Salva per collegarti e fissare l'inventario degli strumenti. Aprire o annullare il modello non contatta Exa. Le query di ricerca e gli URL richiesti vengono inviati a Exa quando questi strumenti vengono eseguiti.

Server MCP — issue tracker

1. Registra Issues, MCP, https://mcp.example-tracker.dev/mcp, auth header con X-Api-Key.
2. search_issues in sola lettura esegue; create_issue chiede.
3. issues__search_issues esegue e issues__create_issue mostra gli argomenti.

Variabili d'ambiente

Variabile	Effetto
TOOLS_ACCESS_MODE	Fissa admins o all-users e blocca l'interruttore.
TOOLS_PRIVATE_NETWORK_ALLOWLIST	Host esatti autorizzati a risolvere indirizzi privati.

Limiti

• Le chiamate girano sul WebSocket e sul percorso duraturo; l'endpoint REST legacy non esegue il loop.
• Le menzioni @model nei canali eseguono lo stesso loop sul catalogo del membro che menziona, con una differenza: non c'è nessuno da interpellare, quindi uno strumento con effetti collaterali privo di un'approvazione duratura viene rifiutato subito anziché mettersi in attesa. Gli strumenti in sola lettura eseguono normalmente.
• Gli agenti Work chiamano gli stessi server attraverso lo stesso gateway: solo esecuzioni con rete, server senza credenziali filtrati al momento dell'offerta, strumenti con effetti collaterali soggetti alle approvazioni di Work.
• Gemini e agent CLI non ricevono strumenti; Ollama, OpenAI-compatible, Responses-API e Anthropic sì.
• L'OAuth interattivo è solo per MCP: un server OpenAPI usa ancora una credenziale statica per utente. Il flusso è la concessione authorization-code con PKCE; i flussi device-code e client-credentials non sono offerti, e un server di autorizzazione che non pubblica metadati (o non offre un endpoint di registrazione né un ID client fornito dall'amministratore) non può essere collegato.
• Gli endpoint OAuth scoperti devono essere https; http in chiaro è accettato solo per loopback, per un provider in esecuzione sulla stessa macchina durante lo sviluppo.
• L'URI di reindirizzamento deriva da BASE_URL (o dal primo CORS_ORIGIN), quindi quel valore deve essere l'indirizzo effettivamente raggiunto dal browser e deve essere registrato presso i provider che fissano gli URI di reindirizzamento.