Questa guida spiega come creare, configurare e integrare strumenti AI personalizzati all’interno del plugin Discourse AI, consentendo agli amministratori di estendere le capacità del bot con funzioni JavaScript definite dall’utente.
Livello utente richiesto: Amministratore
Gli strumenti sono funzionalità programmabili che possono essere utilizzate dal bot AI per eseguire attività specifiche o recuperare informazioni oltre le semplici risposte basate su testo. Questi strumenti sono script o integrazioni che consentono al bot di interagire con API esterne, manipolare dati o eseguire funzioni aggiuntive per estenderne le capacità.
Sommario
Questa documentazione copre:
- Creazione di un nuovo strumento AI personalizzato
- Configurazione dei parametri e degli script dello strumento
- API disponibili per gli script degli strumenti
- Integrazione di strumenti personalizzati con le persona AI
- Test e risoluzione dei problemi degli strumenti personalizzati
Creazione di un nuovo strumento AI personalizzato
Per creare un nuovo strumento AI:
- Naviga su Pannello Amministrazione > Plugin > Discourse AI > Strumenti (Tools)
- Clicca su “Nuovo Strumento” (New Tool) (puoi usare le preimpostazioni esistenti per imparare le opzioni)
- Compila i seguenti campi:
- Nome (Name): Il nome dello strumento presentato all’LLM
- Descrizione (Description): La descrizione dello strumento presentata all’LLM
- Sommario (Summary): Riepilogo di ciò che fa lo strumento per assistere gli utenti (visualizzato nei dettagli)
- Parametri (Parameters): Definisci gli input di cui il tuo strumento ha bisogno come presentati all’LLM
- Script: Il codice JavaScript che alimenta il tuo strumento
- Clicca su “Salva” (Save)
Configurazione degli script degli strumenti
API disponibili
I tuoi script degli strumenti hanno accesso alle seguenti API:
-
Richieste HTTP:
http.get(url, options) http.post(url, options) http.put(url, options) http.patch(url, options) http.delete(url, options)Usale per interagire con servizi esterni. Puoi usare
optionsper specificare intestazioni HTTP e corpo:http.get(url, { headers: { "Authorization": "Bearer key" } }) http.post(url, { headers: { "Content-Type": "application/json" }, body: { key: "value" } }) http.patch(url, { headers: { "Authorization": "Bearer key" }, body: "some body" }) http.delete(url, { headers: { "Authorization": "Bearer key" } }) http.put(url, { headers: { "Authorization": "Bearer key" }, body: "some body" })Tutti i metodi HTTP restituiscono
{ status: number, body: string }. -
Integrazione LLM (Language Model):
llm.truncate(text, length)Tronca il testo a una lunghezza di token specificata in base al tokenizer dell’LLM configurato.
llm.generate(prompt, options)Genera testo utilizzando l’LLM configurato. Il prompt può essere una semplice stringa o un oggetto strutturato come
{ messages: [{ type: "system", content: "..." }, { type: "user", content: "..." }] }. Le opzioni includonojson: trueper richiedere e analizzare automaticamente l’output JSON, oltre atemperature,top_p,max_tokensestop_sequences. -
Integrazione caricamento personalizzato (RAG)
index.search(query, { filenames: ["file.pdf"], limit: 10 })Cerca frammenti di documenti RAG indicizzati allegati a questo strumento. Restituisce
Array<{ fragment: string, metadata: string | null }>ordinati per rilevanza. Il limite predefinito è 10, massimo 200.index.getFile(filename)Recupera il contenuto completo di un file RAG caricato tramite il suo nome esatto. Restituisce il testo completo o
nullse non trovato. -
Supporto per il caricamento (Upload)
upload.create(filename, base_64_content)Crea un nuovo caricamento. Restituisce
{ id: number, url: string, short_url: string }.upload.getUrl(shortUrl)Dato un URL breve (es.
upload://12345), restituisce l’URL completo compatibile con CDN.upload.getBase64(uploadIdOrShortUrl, maxPixels)Recupera il contenuto codificato in base64 di un caricamento esistente. Accetta un ID di caricamento (numero) o un URL breve (stringa). Parametro opzionale
maxPixelsper il ridimensionamento automatico delle immagini (default: 10.000.000). -
Controllo della catena di esecuzione (Execution chain control)
chain.setCustomRaw(raw)Imposta il contenuto grezzo finale del post del bot e interrompe la catena di esecuzione dello strumento. Utile per strumenti che generano direttamente la risposta completa (ad esempio, strumenti di generazione di immagini).
-
Gestione dei segreti (Secrets management)
secrets.get(alias)Restituisce il valore della credenziale associata all’alias fornito. Gli alias sono definiti nella configurazione dei contratti segreti dello strumento e collegati ai Segreti AI nel pannello di amministrazione. Genera un errore se l’alias non è dichiarato, non è collegato o la credenziale è mancante.
const apiKey = secrets.get("my_api_key"); -
Integrazione Discourse
Gli strumenti possono interagire direttamente con i dati di Discourse:
discourse.baseUrl // L'URL di base del sito discourse.search(params) // Esegue una ricerca in Discourse discourse.getPost(post_id) // Ottiene i dettagli del post (include il contenuto grezzo) discourse.getTopic(topic_id) // Ottiene i dettagli del topic (tag, categoria, ecc.) discourse.getUser(id_or_username) // Ottiene i dettagli dell'utente discourse.createTopic(params) // Crea un nuovo topic discourse.createPost(params) // Crea un nuovo post/risposta discourse.editPost(post_id, raw, options) // Modifica il contenuto di un post discourse.editTopic(topic_id, updates, options) // Modifica le proprietà del topic (tag, categoria, visibilità) discourse.createChatMessage(params) // Invia un messaggio di chat discourse.createStagedUser(params) // Crea un utente in attesa di conferma discourse.getAgent(name) // Ottiene un altro agente AI (con metodo respondTo) discourse.updateAgent(name, updates) // Aggiorna la configurazione di un agente AI discourse.getCustomField(type, id, key) // Legge un campo personalizzato su post/topic/utente discourse.setCustomField(type, id, key, value) // Imposta un campo personalizzato su post/topic/utente -
Oggetto Contesto (Context object)
L’oggetto
contextfornisce informazioni su dove è in esecuzione lo strumento:- Contesto conversazione Bot:
context.post_id,context.topic_id,context.private_message,context.participants,context.username,context.user_id - Contesto Chat:
context.message_id,context.channel_id,context.username - Contesto Automazione:
context.post_id,context.topic_id,context.username,context.user_id,context.feature_name,context.feature_context - Proprietà comuni:
context.site_url,context.site_title,context.site_description
- Contesto conversazione Bot:
Funzioni richieste
Il tuo script deve implementare:
invoke(params): La funzione principale che viene eseguita quando viene chiamato lo strumento
Può implementare facoltativamente:
details(): Restituisce una stringa (può includere HTML di base) che descrive l’esecuzione dello strumento, visualizzata nell’interfaccia di chatcustomSystemMessage(): Chiamata durante l’assemblaggio del prompt (non durante l’invocazione dello strumento). Restituisce una stringa aggiunta al prompt di sistema, onull/undefinedper saltare. Ha accesso agli oggetticontext,discourseeindex.
Esempio di script:
function invoke(params) {
let result = http.get("https://api.example.com/data?query=" + params.query);
return JSON.parse(result.body);
}
function details() {
return "Dati recuperati dall'API di Esempio";
}
Limitazioni e sicurezza
- Timeout di Esecuzione: Timeout predefinito di 2000 ms di tempo di elaborazione dello script. Il timer si interrompe durante le richieste HTTP esterne (
http.*) e le chiamate LLM (llm.generate), quindi conta solo il tempo di elaborazione dello script stesso. - Memoria: Limite massimo di heap V8 di 10MB
- Richieste HTTP: Massimo 20 richieste per esecuzione dello strumento
- Ambiente Sandboxed: Gli script vengono eseguiti in un ambiente JavaScript V8 ristretto (tramite MiniRacer). Nessun accesso alle globali del browser, al file system dell’host o alle librerie lato server. Le richieste di rete sono sottoposte a proxy tramite il backend di Discourse.
Test del tuo strumento
Dovresti testare ogni strumento che costruisci per assicurarti che i risultati forniti all’LLM corrispondano alle tue aspettative.
Integrazione degli strumenti con le persona AI
Per aggiungere il tuo strumento personalizzato a una Persona AI:
- Vai su Pannello Amministrazione > Plugin > Discourse AI > Persona (Personas)
- Modifica una persona esistente o creane una nuova
- Nella sezione “Strumenti” (Tools), vedrai elencati i tuoi strumenti personalizzati accanto agli strumenti predefiniti
- Seleziona il tuo strumento personalizzato per aggiungerlo alla persona
Strumenti personalizzati in azione
Una volta fornito lo strumento personalizzato al tuo LLM, questo può utilizzarlo per migliorare la conversazione.
Risoluzione dei problemi
Se il tuo strumento non funziona come previsto:
- Usa l’interfaccia di Test per assicurarti che si comporti come previsto per i tuoi input.
- Assicurati che il tuo gruppo sia in
ai_bot_debugging_allowed_groups. I membri di questo gruppo hanno pieno accesso alle trascrizioni del bot; puoi visualizzare i log AI lì. - Se sta succedendo qualcosa di inaspettato, visita
https://NOME_SITO/logsper verificare la presenza di errori.
