Usa Beeuni come backend per gli agenti del tuo prodotto

Usa l’API Beeuni o l’SDK TypeScript per creare sessioni agente dalla tua applicazione. Il tuo prodotto gestisce l’interfaccia e i suoi utenti; Beeuni esegue gli strumenti dell’agente e restituisce messaggi e file.

Immagina uno strumento per gli acquisti che confronta i fornitori. Un utente seleziona prodotti e fornitori approvati; l’agente visita le pagine pubbliche dei loro cataloghi, legge i listini da un servizio di documenti collegato e prepara una tabella comparativa. La tua applicazione gestisce l’accesso e la revisione, mentre la sessione Beeuni raccoglie il materiale ed esegue il confronto.

Definisci l’attività che l’interfaccia invia

Elenca gli input, le azioni consentite, il formato di output e i casi di errore. Nell’esempio del catalogo, fornisci le pagine dei fornitori approvati, i riferimenti ai documenti di catalogo collegati e i campi da confrontare. Richiedi una riga per prodotto, con il prezzo indicato, la valuta e un riferimento alla fonte. Le dimensioni mancanti devono essere indicate come sconosciute. L’attività non deve effettuare ordini.

• Responsabilità dell’applicazione: autenticare le persone, decidere chi può accedere a ciascuna attività, convalidare gli input e presentare il risultato.
• Configurazione del progetto: scegli l’agente, il modello, le competenze e gli strumenti autorizzati necessari per questo tipo di lavoro.
• Attività della sessione: invia la richiesta, segui i progressi ed esamina i messaggi e i file di output restituiti.

Consenti alla sessione di accedere alle fonti necessarie

Configura il progetto con gli strumenti browser e connettore necessari per l’attività. Per un servizio di documenti privati, collega un account e autorizza l’agente ad accedere al connettore pertinente. Un link inserito in una richiesta non concede di per sé l’accesso. Assicurati che l’account selezionato e le fonti consentite siano coerenti con il cliente che ha inviato l’attività; la guida ai connettori spiega l’accesso agli account.

L’agente può quindi leggere i documenti selezionati tramite questi strumenti, visitare le pagine pubbliche dei prodotti e scrivere uno script per allineare i codici prodotto e le dimensioni delle confezioni. Chiedigli di salvare, insieme al risultato, i valori recuperati, le posizioni delle fonti e gli orari di recupero. Se non è possibile leggere un catalogo o una pagina richiede un altro accesso, segnala il problema nell’interfaccia invece di inventare un prezzo.

Conserva le credenziali sul tuo server

La guida all’SDK spiega come installare @beeuni/sdk, creare un client e autenticare le richieste. Conserva la chiave API sul tuo server, fuori dal codice del browser.

Decidi a quali progetti Beeuni può accedere ciascun cliente. Se necessario, mantieni separati i rispettivi file e account collegati e controlla l’accesso sul tuo server prima di inoltrare le richieste. La guida all’autenticazione illustra i metodi di accesso disponibili.

Mostra i progressi e gestisci le riconnessioni

L’SDK permette di creare sessioni, attendere che siano pronte e inviare una richiesta. L’esempio completo illustra come ricevere gli eventi e leggere la risposta. Usa questi eventi per mostrare i progressi effettivi. Le indicazioni «Apertura delle pagine dei fornitori», «Confronto dei prodotti» e «Risultato pronto» dovrebbero corrispondere ciascuna a un’attività o a uno stato che puoi osservare.

Assegna a ogni confronto una registrazione dell’attività nella tua applicazione. Salva i riferimenti alle fonti selezionate, le colonne richieste, gli ID del progetto e della sessione Beeuni e la posizione dell’output non appena diventa disponibile. Questa registrazione collega la schermata di revisione al lavoro già in corso.

Application task record — illustrative fields, not an SDK payload
app_task_id
approved_source_references
requested_columns
beeuni_project_id
beeuni_session_id
output_reference
review_status

Immagina un utente che seleziona tre cataloghi di fornitori e poi aggiorna la pagina. L’interfaccia aggiornata recupera l’attività dell’applicazione e la sessione Beeuni già esistente. Legge i progressi salvati e riprende a seguirne lo svolgimento. Creare una nuova sessione a ogni caricamento della pagina duplicherebbe l’attività.

La connessione può interrompersi anche prima che il tuo server riceva la conferma dell’invio. L’esito è incerto, ma questo non dimostra che non sia successo nulla. Controlla la sessione prima di inviare di nuovo la richiesta. Se non riesci ancora a capire se è stata accettata, mostra l’incertezza invece di avviare automaticamente un altro confronto.

Controlla il risultato nella tua applicazione

Per il confronto dei cataloghi, verifica che siano presenti le colonne richieste, che i file siano leggibili e che le fonti siano indicate; controlla inoltre i prodotti che non è stato possibile abbinare. Le diverse dimensioni delle confezioni sono un problema frequente: non si può confrontare direttamente il prezzo di una scatola da dodici con quello di un singolo articolo. Conserva l’importo e l’unità indicati e aggiungi un prezzo normalizzato solo quando la fonte consente di effettuare la conversione.

La schermata di revisione dovrebbe permettere all’utente di aprire la fonte da cui proviene un prezzo e vedere gli abbinamenti non risolti. Il file può essere pronto anche se alcune righe richiedono ancora una revisione; gestisci questi stati separatamente nella tua applicazione.

Consenti agli utenti di correggere un risultato senza perderne il contesto

Supponiamo che due fornitori usino nomi diversi per la stessa sedia. L’agente le lascia come prodotti separati e chi revisiona riconosce che si tratta dello stesso articolo. Una correzione utile include le due righe di origine e la relazione desiderata: «Confronta questi prodotti come se fossero lo stesso articolo, ma mantieni separati la finitura e il formato della confezione indicati». Inviare soltanto «riprova» lascia all’agente il compito di indovinare cosa non andava.

Registra la correzione accanto all’attività e conserva il risultato precedente. Il risultato successivo potrebbe correggere l’abbinamento del prodotto ma modificare un’altra riga. Mostra il confronto aggiornato e la versione precedente, così chi revisiona può controllarli entrambi. Decidi quale versione fornisce il pulsante di download e registra quale è stata approvata.

L’approvazione potrebbe pubblicare il confronto in una schermata interna per gli acquisti. Inviare un ordine a un fornitore è un’azione distinta, con autorizzazioni e conferma proprie. Definisci questo limite nell’applicazione prima di concedere all’agente l’accesso agli strumenti per gli acquisti. Completare un foglio di calcolo non dovrebbe attivare automaticamente un ordine.

Decidi quanto lavoro può avviare una richiesta

Imposta limiti pratici per l’invio, come il numero di cataloghi e il lavoro consentito in una singola richiesta. Confrontare tre brevi listini è diverso dal riconciliare un intero archivio di prodotti. Mostra l’ambito accettato prima di iniziare, così una persona può ridurre la richiesta o scegliere un’attività in background.

Quando disponibili, leggi le informazioni sull’utilizzo e sui costi dalla piattaforma, invece di calcolare l’importo finale in base alla lunghezza dei messaggi. Se il tuo prodotto richiede un limite di spesa rigido o la garanzia di annullamento, verifica come l’integrazione lo applica. Un conto alla rovescia o un pulsante «Interrompi» non dimostrano, da soli, che il lavoro e i costi siano cessati.

Prova l’integrazione con casi che puoi verificare manualmente

Prepara un piccolo insieme di cataloghi con interpretazioni attese: un listino leggibile e corretto, una scansione illeggibile, due valute, formati delle confezioni in conflitto e un prodotto senza un abbinamento chiaro. Usali quando modifichi il modello, le istruzioni o la configurazione del progetto. Confronta le righe risultanti e i riferimenti alle fonti, compresi i casi che l’agente lascia irrisolti.

Esci anche dalla pagina durante l’esecuzione, poi torna e invia una correzione dopo la comparsa del risultato. Controlla quale output viene scaricato e se un’altra persona autenticata può accedere all’attività. Il catalogo potrebbe essere interpretato correttamente mentre la tua applicazione mostra la versione sbagliata o la rende visibile all’account errato. Verifica insieme il risultato dell’agente e l’interfaccia che lo circonda.