Instrumente de chat

Chatul poate permite modelului să apeleze instrumente. Un schimb cu instrumente active rulează o buclă nativă cu mai multe runde: modelul solicită un instrument, Libre WebUI îl execută sub identitatea și permisiunile utilizatorului care îl invocă, rezultatul revine la model, iar bucla continuă până când modelul răspunde — cel mult opt runde per schimb și opt apeluri per rundă. Oprirea anulează apelul modelului, orice apel de instrument în desfășurare și orice așteptare de aprobare.

Apelurile instrumentelor sunt înregistrate ca evenimente normalizate (chat.tool-call.v1, chat.tool-result.v1, chat.approval.v1) care circulă identic pe calea WebSocket privată și fluxul de evenimente persistent, astfel încât o reîmprospătare sau reconectare redă aceeași stare. Schimbul finalizat își stochează apelurile, cu previzualizări limitate ale rezultatelor, în mesajul asistentului.

Activarea instrumentelor

Instrumentele sunt dezactivate implicit. Un administrator le activează în Setări → Gestionarea utilizatorilor (numai administratori sau toți utilizatorii); fiecare schimb le selectează apoi prin cheia din editor, care deschide un selector: un comutator principal și câte o casetă pentru fiecare instrument integrat și server înregistrat, astfel încât schimbul să ruleze exact cu instrumentele alese. Selectorul poate restrânge ceea ce leagă un profil, dar nu poate extinde. Chaturile private (incognito) nu oferă niciodată instrumente: un apel de instrument este o acțiune orientată spre exterior și poate lăsa aprobări și înregistrări de audit.

Un profil de asistent (personaj) poate limita instrumentele oferite: serverele de instrumente legate, un subset de instrumente integrate, abilitățile și colecțiile de cunoștințe legate restricționează ceea ce vede modelul în sesiunile care folosesc acel profil.

Instrumente integrate

Chatul include treisprezece instrumente primare (toate numai pentru citire, cu excepția instrumentelor care modifică notițe și calendarul și care trec prin fluxul de aprobare a efectelor secundare):

• web_search — motorul de căutare configurat de administrator, respectând modul de acces la căutarea web.
• search_documents — căutare hibridă în documentele încărcate și colecțiile de cunoștințe ale utilizatorului, inclusiv colecțiile partajate cu acesta (legăturile profilului pot limita colecțiile); fiecare pasaj este citat cu fragmentul și poziția sursă.
• list_documents — listează documentele din domeniul acestui chat cu id-urile, tipurile și dimensiunile lor, astfel încât modelul să decidă ce să citească.
• read_document — citește o fereastră limitată a unui document disponibil, după id și decalaj, etichetată cu poziția sursă, pentru parcurgerea unui fișier la care regăsirea singură nu poate răspunde.
• load_skill — încarcă instrucțiunile complete ale unei abilități după slug; descrierea instrumentului conține manifestul abilităților activate ale utilizatorului, astfel încât acestea rămân inactive până când modelul are nevoie de una. Dacă abilitatea include fișiere însoțitoare, instrucțiunile încărcate se încheie cu inventarul fișierelor.
• read_skill_file — citește un fișier însoțitor inclus cu o abilitate, după slug și cale relativă, astfel încât un document mare de referință să nu consume context până când modelul îl deschide efectiv.
• list_notes — listează notițele proprii și partajate ale utilizatorului, cu id-urile lor.
• read_note — citește conținutul integral al unei notițe după id.
• create_note — creează o notiță (are efect secundar și necesită aprobare).
• update_note — înlocuiește conținutul unei notițe; starea anterioară este păstrată ca revizie restaurabilă, astfel încât o editare a modelului este întotdeauna reversibilă (are efect secundar și necesită aprobare).
• list_calendar_events — listează evenimentele proprii și partajate din calendarul utilizatorului într-un interval de milisecunde de la epoch.
• create_calendar_event — creează un eveniment în calendar (are efect secundar și necesită aprobare).
• delete_calendar_event — șterge un eveniment din calendar după id (are efect secundar și necesită aprobare).

Servere de instrumente

Administratorii înregistrează servere externe de instrumente în Setări → Instrumente (șabloanele inițiale precompletează formularul, inclusiv cu un API demonstrativ public sigur):

• OpenAPI: o specificație JSON OpenAPI 3.x este preluată o dată și fixată cu un digest SHA-256. Fiecare operație devine un instrument; operațiile GET sunt clasificate numai pentru citire, iar toate celelalte drept efecte secundare, până când un administrator suprascrie clasificarea per instrument. Execuția reconstruiește apelul din operația fixată — argumentele modelului nu aleg niciodată destinația.
• MCP (Streamable HTTP): lista instrumentelor serverului este preluată prin JSON-RPC și fixată la fel. annotations.readOnlyHint marchează un instrument numai pentru citire. Serverele MCP stdio nu sunt acceptate intenționat: procesele externe nu rulează niciodată în procesul web.

Un inventar schimbat intră în vigoare numai când un administrator reîmprospătează serverul, avansând revizia fixată și păstrând suprascrierile per instrument. Disponibilitatea per server poate fi numai pentru administratori, pentru toți utilizatorii sau bazată pe permisiuni prin modelul comun de acordare a resurselor (permisiuni pentru utilizatori și grupuri pe serverul de instrumente).

Credențiale

Serverele care necesită autentificare folosesc credențiale per utilizator (token bearer sau un antet denumit). Fiecare secret este criptat cu date autentificate suplimentare care îl leagă de utilizatorul și serverul exacte, este introdus de fiecare utilizator în Setări → Instrumente și nu este partajat niciodată între conturi.

Politica traficului de ieșire

Fiecare cerere de instrument își rezolvă singură destinația, refuză spațiile de adrese private, loopback și de metadate și fixează conexiunea la adresa rezolvată, astfel încât o re-legare DNS să nu poată redirecționa apelul. Răspunsurile de redirecționare sunt refuzate. Răspunsurile au o limită de dimensiune, iar fiecare apel are un timeout strict. Numele exacte ale gazdelor interne pot fi permise cu TOOLS_PRIVATE_NETWORK_ALLOWLIST (separate prin virgulă); gazdele permise rămân fixate și limitate. Ieșirea instrumentului reintră în model ca text care nu este de încredere.

Aprobări

Instrumentele numai pentru citire rulează fără confirmare. Un instrument cu efect secundar întrerupe schimbul și întreabă utilizatorul: permite o dată, permite pentru acest chat, permite întotdeauna acest instrument pe server sau refuză. Deciziile sunt persistente — o permisiune „întotdeauna” supraviețuiește repornirilor și poate fi revocată din Setări → Instrumente — iar o cerere în așteptare expiră după două minute, ceea ce modelul vede ca refuz. Refuzurile și timeout-urile nu execută niciodată apelul. Fiecare decizie și fiecare apel lasă un eveniment de audit de securitate cenzurat.

Exemple

Activați mai întâi comutatorul cu cheia din editor; fiecare exemplu de mai jos este un mesaj obișnuit de chat.

web_search — căutarea informațiilor

Ce s-a schimbat în cea mai recentă versiune SQLite? Caută pe web înainte să răspunzi.

Modelul apelează web_search cu o interogare precum {"query": "SQLite latest release changelog"}, cardul apelului arată fragmentele de rezultate primite, iar răspunsul citează ceea ce a găsit. Necesită configurarea căutării web și permisiunea pentru contul dvs.

search_documents — întrebări despre fișierele proprii

Încărcați un PDF sau adăugați documente într-o colecție de cunoștințe, apoi:

Caută în documentele mele clauza de reziliere și citeaz-o exact.

Modelul apelează search_documents cu {"query": "termination clause"} și primește pasaje potrivite, etichetate cu documentul sursă, astfel încât răspunsul să le poată cita și atribui.

load_skill — aplicarea unei abilități salvate

Creați o abilitate în Setări → Abilități (de exemplu $release-notes — modul în care doriți să fie scrise notele de versiune), apoi:

Redactează note de versiune pentru această diferență folosind $release-notes.

Modelul vede abilitatea în manifest, apelează load_skill {"slug": "release-notes"} pentru a prelua instrucțiunile complete și le urmează. Tastarea $ în editor completează automat slug-urile abilităților.

Un server OpenAPI — de exemplu un API meteo

1. Setări → Instrumente → Înregistrează serverul: nume Weather, tip OpenAPI, URL de bază https://api.example-weather.dev, URL specificație https://api.example-weather.dev/openapi.json, mod de autentificare bearer.

2. Specificația este fixată, iar operațiile sale apar ca instrumente — de exemplu getForecast (GET, numai citire) și createAlert (POST, efect secundar).

3. Fiecare utilizator care îl dorește își salvează cheia API proprie pe cardul serverului.

4. În chat:

   Care este prognoza pentru Montreal în acest weekend?

   Modelul apelează weather__getForecast {"city": "Montreal"}, care rulează imediat — instrumentele numai pentru citire nu cer confirmare.

   Anunță-mă dacă temperatura scade sub -20 în această seară.

   weather__createAlert are un efect secundar, astfel încât schimbul se oprește cu un card de aprobare: Permite o dată, Permite pentru acest chat, Permite întotdeauna sau Refuză. Nu se trimite nimic până când alegeți.

Un server MCP — de exemplu un sistem de urmărire a problemelor

1. Setări → Instrumente → Înregistrează serverul: nume Issues, tip MCP, URL de bază https://mcp.example-tracker.dev/mcp, mod de autentificare header cu numele antetului X-Api-Key.

2. Lista instrumentelor este fixată; instrumentele marcate de server numai pentru citire (precum search_issues) rulează liber, iar toate celelalte (precum create_issue) cer mai întâi aprobarea.

3. În chat:

   Găsește problemele deschise care menționează „database lock” și înregistrează una nouă care rezumă tiparul.

   issues__search_issues rulează imediat; issues__create_issue afișează argumentele exacte în cardul de aprobare, astfel încât să puteți citi ce va fi înregistrat înainte să permiteți.

Variabile de mediu

Variabilă	Efect
TOOLS_ACCESS_MODE	Fixează funcția de instrumente la admins sau all-users și blochează comutatorul administratorului.
TOOLS_PRIVATE_NETWORK_ALLOWLIST	Nume exacte de gazde pe care serverele de instrumente le pot rezolva la adrese private (listă separată prin virgule).

Limite

• Apelurile instrumentelor rulează pe calea WebSocket (transportul sesiunilor private este exclus prin proiectare) și pe calea de generare persistentă folosită pentru chaturile stocate. Endpoint-ul vechi de flux REST nu rulează bucla instrumentelor.
• Agenții Work apelează aceleași servere prin același gateway: numai execuții cu rețea, serverele fără credențiale salvate sunt filtrate la ofertare, iar instrumentele cu efect secundar trec prin aprobările Work.
• Modelele Gemini și agent CLI nu primesc instrumente; furnizorii Ollama, compatibili cu OpenAI, Responses-API și Anthropic le primesc.
• Serverele MCP se autentifică prin credențiale statice per utilizator; un server MCP care acceptă numai OAuth interactiv nu poate fi înregistrat încă.