Quickstart: il primo agente in 10 minuti
Tempo richiesto: circa 10 minuti.
Questa guida porta dalla creazione di una base di conoscenza a un agente provato nell'anteprima e raggiungibile con una chiave API, in quattro passi.
Prerequisiti
I primi tre passi richiedono un utente con ruolo operatore o amministratore: entrambi i ruoli predefiniti possono creare basi di conoscenza e agenti. Il quarto passo richiede il ruolo amministratore e la capacità Accesso API attiva per l'organizzazione, perché le chiavi API si gestiscono nel gruppo Impostazioni, che gli operatori non vedono. Occorre inoltre un documento di esempio (PDF, Word, testo o CSV) da caricare come primo contenuto.
Passo 1 — Creare una base di conoscenza e caricare un documento
- Aprire Conoscenza dal menu laterale e selezionare Nuova base di conoscenza. Lo stesso modulo si apre dalla card Carica conoscenza della Home oppure cercando "Nuova base di conoscenza" con Cerca (Ctrl+K).
- Nella sezione Informazioni generali compilare Nome e verificare che Lingue dei contenuti comprenda la lingua del documento. Gli altri campi e le sezioni Vector store e Strategia di chunking possono restare sui valori proposti.
- Selezionare Crea: la console apre la base di conoscenza sulla scheda Documenti.
- Selezionare Carica documenti e caricare il documento di esempio dalla finestra Carica documenti; in alternativa, trascinare il file sulla pagina.
Il documento compare nell'elenco con lo stato In coda e passa a Indicizzato al termine dell'indicizzazione; la colonna Frammenti indica in quante parti è stato suddiviso. Se l'elaborazione non riesce, lo stato diventa Errore.
Il significato di ciascun campo del modulo è descritto in Creare una base di conoscenza; il caricamento, compresi i documenti scansionati, in Caricare documenti.
Passo 2 — Creare l'agente
- Aprire Agenti e selezionare Nuovo agente, oppure usare la card Crea un agente della Home. La console crea subito una bozza chiamata "Nuovo agente", con il modello proposto per le prove o, se non è disponibile, con il primo modello disponibile per l'organizzazione, e apre la pagina dell'agente. Se si lascia la pagina senza modificare nulla, la bozza viene eliminata.
- Scrivere nome e descrizione direttamente nell'intestazione della pagina.
- Aprire la sezione Istruzioni e scrivere le istruzioni dell'agente, ad esempio "Rispondi alle domande dei clienti utilizzando la base di conoscenza collegata".
- Aprire la sezione Conoscenza e selezionare, nell'elenco Basi di conoscenza, la base creata al passo 1; il campo Cerca fra le basi di conoscenza aiuta a trovarla.
La pagina non ha un pulsante di salvataggio: ogni modifica viene salvata automaticamente. Mentre il salvataggio è in corso l'intestazione mostra Salvataggio…; se non riesce, mostra Non salvato. Le altre sezioni della configurazione, cioè Modello, Strumenti e connettori, Passaggio a operatore, Guardrail e Avanzate, sono descritte in Creare e configurare un agente.
Passo 3 — Provare l'agente nell'anteprima
A destra della configurazione, sotto il pannello Navigazione che elenca le sezioni, il pannello Anteprima chat permette di conversare con l'agente senza lasciare la pagina. Il pannello si abilita quando le modifiche sono salvate: finché un salvataggio è in corso mostra il messaggio "Salva le modifiche per provare l'agente aggiornato".
- Nel pannello Anteprima chat scrivere una domanda sul contenuto del documento caricato e inviarla.
- Verificare che la risposta citi il documento tra le fonti.
- Per ripartire da una conversazione vuota, selezionare l'icona Nuova conversazione nella barra del pannello.
Quando l'agente risponde come previsto, portarlo nello stato Attivo prima di collegarlo a un canale, come Askme Chat, o a un'integrazione: selezionare il chip di stato Bozza nell'intestazione e scegliere Attivo. Il cambio di stato viene rifiutato se le Istruzioni sono vuote. Gli stati disponibili sono Bozza, Attivo, In pausa e Archiviato; Metti in pausa, Riprendi e Archivia si trovano anche nel menu Altre azioni.
In alternativa all'anteprima, la voce Chat del menu laterale apre la conversazione a tutta pagina con gli agenti in stato Attivo, scelti con Seleziona agente; le fonti di ogni risposta si consultano nel pannello Fonti. Il funzionamento dell'anteprima è descritto in Anteprima chat, la conversazione in Conversare con un agente.
Passo 4 — Ottenere una chiave API
- Nel menu laterale aprire Impostazioni > API: la pagina si apre su Chiavi API.
- Selezionare Nuova chiave.
- Compilare i campi della finestra Nuova chiave come indicato nella tabella seguente e selezionare Crea.
- Nella finestra Chiave API generata copiare subito la chiave: non sarà più visibile e non è possibile rileggerla.
| Campo | Valore consigliato |
|---|---|
| Nome chiave | Un nome che identifichi l'integrazione, ad esempio "Integrazione sito" |
| Funzioni della chiave | Tutte le funzioni, oppure le sole funzioni che servono all'integrazione. La gestione di utenti, ruoli e chiavi API non è compresa in Tutte le funzioni e va scelta una per una solo se necessaria |
| Scadenza (giorni) | Vuoto per una chiave senza scadenza, oppure il numero di giorni di validità |
| App di origine | Il prodotto che userà la chiave, ad esempio Askme Chat; Generale per un'integrazione diretta |
La chiave va indicata nell'header X-Api-Key di ogni chiamata. Il menu Altre azioni dell'agente offre anche Esporta, che mostra un esempio di codice per chiamare l'agente, descritto in Esportare un agente come codice. La prima chiamata a un agente è descritta nel Quickstart delle API, la gestione delle chiavi in Chiavi API.
Risultato atteso
Al termine dei quattro passi sono disponibili una base di conoscenza con almeno un documento indicizzato, un agente attivo che la consulta e cita le fonti nell'anteprima, e una chiave API con cui un modulo Askme o un'integrazione può interrogare l'agente.
Problemi comuni
| Problema | Causa | Soluzione |
|---|---|---|
| L'agente non passa allo stato Attivo | Le Istruzioni sono vuote | Compilare la sezione Istruzioni e ripetere il cambio di stato |
| Il pannello Anteprima chat resta bloccato | Un salvataggio è ancora in corso, oppure non è riuscito (Non salvato) | Attendere la fine del salvataggio o correggere i campi segnalati |
| La risposta non cita alcuna fonte | Il documento non è ancora Indicizzato, oppure la base di conoscenza non è selezionata nella sezione Conoscenza | Verificare lo stato del documento e la sezione Conoscenza, come descritto in Conoscenza dell'agente |
| Il documento resta a lungo In coda | File di grandi dimensioni o documento scansionato da leggere con l'OCR | Attendere il completamento; vedere Caricare documenti |
| Selezionando Nuovo agente la bozza non viene creata | L'organizzazione non ha modelli disponibili | Rivolgersi all'amministratore dell'organizzazione |
| La voce Impostazioni non compare nel menu | L'utente ha il ruolo operatore | Chiedere a un amministratore di creare la chiave API |