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 (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.

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.

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.

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.
• 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ì.
• MCP usa credenziali statiche per utente; server solo OAuth interattivo non sono ancora registrabili.