L'era digitale continua a evolvere rapidamente, e con essa la necessità di applicazioni più intelligenti e reattive. In questo contesto, l'integrazione di capacità di intelligenza artificiale generativa all'interno di piattaforme di sviluppo a basso codice rappresenta un passo significativo. Oracle ha compiuto un importante progresso in questa direzione, con l'integrazione degli agenti di intelligenza artificiale generativa OCI (Oracle Cloud Infrastructure) all'interno delle applicazioni Oracle APEX per offrire esperienze conversazionali potenziate dalla Generazione Aumentata di Recupero (RAG).

Gli agenti di intelligenza artificiale generativa OCI sono un servizio completamente gestito che combina modelli linguistici di grandi dimensioni (LLM) con RAG per fornire risposte accurate e in tempo reale dai dati aziendali. Questo servizio consente agli utenti di interagire naturalmente con diverse basi di conoscenza e alimenta agenti virtuali intelligenti che offrono esperienze cliente personalizzate e contestualmente consapevoli.

D'altra parte, Oracle APEX è la piattaforma di sviluppo di applicazioni a basso codice più popolare al mondo, progettata per aiutare gli sviluppatori a costruire e distribuire rapidamente applicazioni web e mobili sicure e scalabili. Semplifica il processo di sviluppo, permettendo di concentrarsi sulla risoluzione dei problemi aziendali mentre APEX gestisce le complessità sottostanti.

L'integrazione degli agenti di intelligenza artificiale generativa OCI con Oracle APEX permette agli sviluppatori di migliorare le loro applicazioni con interfacce di chat intelligenti e guidate dall'IA. Connettendosi a basi di conoscenza archiviate in OCI Object Storage o Oracle Database 23ai, le applicazioni possono fornire agli utenti risposte accurate e contestualmente pertinenti derivate dai dati aziendali.

Cosa sono gli agenti di intelligenza artificiale generativa OCI?

Gli agenti di intelligenza artificiale generativa OCI sono un servizio completamente gestito che combina modelli linguistici di grandi dimensioni con strumenti di intelligenza artificiale per creare agenti virtuali intelligenti. Le caratteristiche principali includono conversazioni multi-turno, ritenzione del contesto, istruzioni personalizzate, barriere di sicurezza (guardrail) per la protezione dei dati e un'opzione di intervento umano (human-in-the-loop). Supporta strumenti come gli strumenti SQL pronti all'uso, gli strumenti RAG pronti all'uso che lavorano con le basi di conoscenza e lo strumento di chiamata di funzioni personalizzate. I casi d'uso tipici vanno dal supporto clienti all'analisi finanziaria e alla pianificazione di viaggi, offrendo risposte basate sull'IA e contestualmente consapevoli, attingendo a fonti di dati aziendali. Per maggiori dettagli, è possibile consultare la documentazione ufficiale.

Cos'è lo strumento RAG pronto all'uso?

Uno strumento RAG negli agenti di intelligenza artificiale generativa recupera informazioni da una o più basi di conoscenza e mira a rispondere con informazioni pertinenti e contestualmente consapevoli in linguaggio naturale.

Lo strumento RAG degli agenti di intelligenza artificiale generativa OCI consente alle applicazioni di fornire risposte accurate e contestualmente consapevoli, recuperando informazioni da una o più basi di conoscenza e generando risposte in linguaggio naturale. Supporta vari metodi di onboarding dei dati e canali di interazione, comprese interfacce di chat e API. Le caratteristiche principali includono capacità di ricerca ibrida (lessicale e semantica), conversazioni multi-turno, opzioni di moderazione dei contenuti e la capacità di interpretare dati da grafici a due assi e tabelle di riferimento in PDF. Inoltre, offre l'attribuzione della fonte per ogni risposta, garantendo trasparenza e responsabilità.

Lo strumento RAG supporta più tipi di dati per le basi di conoscenza:

  • Opzione gestita dal servizio: file di OCI Object Storage, che consentono fino a 1.000 file di testo e PDF da 100 MB ciascuno.
  • Opzioni "Bring Your Own" (BYO): ricerca vettoriale di Oracle Database 23ai e dati ingeriti e indicizzati tramite OCI Search con OpenSearch.

Questo articolo si concentra sull'integrazione dello strumento RAG degli agenti di intelligenza artificiale generativa OCI con Oracle APEX, sfruttando i file di OCI Object Storage come base di conoscenza.

Prerequisiti per la costruzione di questa applicazione

  1. Un account Oracle Cloud Infrastructure.
  2. Un compartimento OCI. È possibile utilizzare il compartimento root della tenancy preconfigurato o crearne uno proprio.
  3. L'utente connesso deve avere i privilegi necessari per creare e gestire istanze di Autonomous Database in questo compartimento. È possibile configurare questi privilegi tramite una politica IAM di OCI.

Fasi per l'integrazione

L'integrazione degli agenti di intelligenza artificiale generativa OCI con le applicazioni Oracle APEX segue una serie di passaggi ben definiti per garantire una perfetta interazione e funzionalità. Questi passaggi guidano lo sviluppatore attraverso la configurazione necessaria sia in OCI che in APEX per abilitare l'esperienza conversazionale RAG.

  1. Creare un agente negli agenti di intelligenza artificiale generativa OCI.
  2. Aggiungere chiavi API nella console OCI.
  3. Creare credenziali web in Oracle APEX.
  4. Gestire documenti in OCI Object Storage con Invoke API.
  5. Creare un lavoro di ingestione utilizzando le API REST di OCI Ingestion Job.
  6. Configurare e invocare l'API REST di creazione sessione.
  7. Creare e personalizzare il report classico per l'interfaccia di chat.
  8. Creare azioni dinamiche per l'integrazione con gli agenti di intelligenza artificiale generativa OCI.

1. Creare un agente negli agenti di intelligenza artificiale generativa OCI

Per creare un agente nel servizio Generative AI Agents, seguire i passaggi descritti di seguito. Assicurarsi di avere le autorizzazioni necessarie per gestire il servizio prima di iniziare.

  1. Navigare nella console OCI: Aprire la console e selezionare una regione dove gli agenti di intelligenza artificiale generativa sono disponibili, come US Midwest (Chicago) o UK South (Londra). Andare alla pagina dell'elenco degli agenti e cliccare su "Crea agente".
  2. Sotto "Informazioni di base", fornire i seguenti dettagli:
    • Nome: Deve iniziare con una lettera o un underscore. È possibile utilizzare lettere, numeri e trattini.
    • Descrizione: Una breve descrizione dello scopo dell'agente.
    • Compartimento: Selezionare il compartimento OCI in cui si desidera creare l'agente.
    • Modello di base: Scegliere il modello linguistico di grandi dimensioni (LLM) che l'agente utilizzerà come base. Ad esempio, "Cohere Command" o "Meta Llama".
    • Istruzioni personalizzate: Fornire istruzioni specifiche per guidare il comportamento dell'agente. Ad esempio, "Sei un assistente per le vendite di prodotti Oracle, rispondi in modo conciso e professionale."
    • Barriere di sicurezza (Guardrails): Configurare le impostazioni di sicurezza per filtrare contenuti inappropriati o indesiderati.
    • Strumenti: Aggiungere lo strumento RAG "pronto all'uso". Sarà qui che si collegheranno le basi di conoscenza. Specificare il tipo di base di conoscenza (ad esempio, "OCI Object Storage") e i dettagli pertinenti (bucket, namespace, prefisso).
  3. Verificare e creare: Rivedere tutti i dettagli e cliccare su "Crea agente". L'agente sarà quindi provisionato e pronto per essere configurato ulteriormente.

2. Aggiungere chiavi API nella console OCI

Per consentire alle applicazioni APEX di comunicare in modo sicuro con i servizi OCI, è fondamentale configurare l'autenticazione tramite chiavi API. Questo passaggio stabilisce una connessione fidata tra l'ambiente APEX e OCI.

  1. Generazione della chiave API: Accedere alla console OCI, navigare nel menu "Identità e sicurezza" e selezionare "Utenti". Selezionare l'utente che avrà i privilegi per accedere ai servizi Generative AI Agents e Object Storage. Sotto le "Risorse" dell'utente, cliccare su "Chiavi API" e poi "Aggiungi chiave API". Generare una coppia di chiavi API (privata e pubblica) o caricare la propria. Scaricare la chiave privata e prendere nota dell'impronta digitale.
  2. Configurazione del file di credenziali OCI: La chiave API generata, insieme all'OCID dell'utente, all'OCID della tenancy e all'impronta digitale della chiave, dovrà essere utilizzata per configurare il file di credenziali OCI. Questo file, tipicamente chiamato `~/.oci/config`, viene utilizzato dagli SDK e dalle API di OCI per l'autenticazione.
  3. Politiche IAM: Assicurarsi che l'utente associato alla chiave API abbia le politiche IAM necessarie per interagire con i servizi "generative-ai-agents" e "object-storage" nel compartimento selezionato. Ad esempio, `Allow group to manage generative-ai-agents in compartment ` e `Allow group to manage object-family in compartment `.

3. Creare credenziali web in Oracle APEX

Le credenziali web in Oracle APEX sono un meccanismo sicuro per archiviare i dettagli di autenticazione per i servizi esterni, evitando di codificare le credenziali direttamente nell'applicazione. Questo è essenziale per chiamare le API REST di OCI in modo sicuro.

  1. Navigare in APEX Builder: Aprire l'applicazione APEX in cui si desidera integrare l'agente AI. Andare a "Componenti condivisi" -> "Credenziali web".
  2. Creare una nuova credenziale: Cliccare su "Crea" per aggiungere una nuova credenziale.
    • Nome: Assegnare un nome significativo, ad esempio "OCI_GENAI_CREDENTIALS".
    • Tipo di autenticazione: Selezionare "Oracle Cloud Infrastructure API Signature (Key)".
    • OCID tenancy: Inserire l'OCID della propria tenancy OCI.
    • OCID utente: Inserire l'OCID dell'utente associato alla chiave API generata nel passaggio precedente.
    • Impronta digitale della chiave: Inserire l'impronta digitale della chiave API.
    • Chiave privata: Incollare il contenuto della chiave privata (il file scaricato) nell'area di testo.
  3. Salvare: Cliccare su "Crea Credenziale web" per salvare. Queste credenziali verranno utilizzate dai processi PL/SQL o dagli handler AJAX in APEX per firmare le richieste alle API OCI.

4. Gestire documenti in OCI Object Storage con Invoke API

La base di conoscenza per lo strumento RAG può essere alimentata da documenti archiviati in OCI Object Storage. APEX può essere utilizzato per fornire un'interfaccia utente per caricare e gestire questi documenti, utilizzando le API REST di OCI.

  1. Interfaccia utente in APEX: Creare una pagina APEX con un'area di caricamento file (ad esempio, un elemento di tipo "File Browse") e un pulsante di invio. Questo consentirà agli utenti di selezionare i file dal proprio computer.
  2. Processo PL/SQL per il caricamento: Associare un processo "On Submit" o una "Dynamic Action" al pulsante. Questo processo utilizzerà il package `APEX_WEB_SERVICE` per chiamare le API REST di OCI Object Storage.
    • URL dell'endpoint: `https://objectstorage..oraclecloud.com/n//b//o/`
    • Metodo HTTP: `PUT`
    • Payload: Il contenuto binario del file caricato.
    • Header di autenticazione: Utilizzare le credenziali web create in precedenza per firmare la richiesta.
  3. Gestione degli oggetti: Oltre al caricamento, si potrebbero implementare funzionalità per elencare, visualizzare o eliminare oggetti dal bucket OCI Object Storage, sempre tramite le rispettive API REST di OCI e il package `APEX_WEB_SERVICE`.

5. Creare un lavoro di ingestione utilizzando le API REST di OCI Ingestion Job

Una volta che i documenti sono stati caricati in OCI Object Storage, devono essere "ingeriti" e indicizzati dal servizio Generative AI Agents per essere utilizzati dallo strumento RAG. Questo processo è avviato tramite le API REST di Ingestion Job.

  1. Endpoint API Ingestion Job: Le API per l'ingestione si trovano all'interno del servizio Generative AI Agents. Sarà necessario identificare l'endpoint corretto per la regione OCI in uso.
  2. Costruire la richiesta API: Creare un processo PL/SQL in APEX (ad esempio, tramite un processo "On Load" di una pagina o una "Dynamic Action" attivata da un pulsante) che costruisce la richiesta JSON per creare un lavoro di ingestione. Il payload JSON includerà:
    • `knowledgeBaseId`: L'OCID della knowledge base associata all'agente AI.
    • `sourceType`: `OBJECT_STORAGE_BUCKET`.
    • `objectStorageBucketDetails`: Contiene `namespace`, `bucketName`, e `prefix` (se i documenti si trovano in una sottocartella).
    • `displayName`: Un nome descrittivo per il lavoro di ingestione.
  3. Chiamare l'API: Utilizzare `APEX_WEB_SERVICE.MAKE_REST_REQUEST` con il metodo `POST`, l'endpoint appropriato, il payload JSON e le credenziali web OCI create precedentemente per l'autenticazione. La risposta API fornirà un `jobId` che può essere utilizzato per monitorare lo stato del lavoro di ingestione.

6. Configurare e invocare l'API REST di creazione sessione

Per avviare una conversazione con l'agente di intelligenza artificiale generativa OCI, è necessario creare una sessione. Questa API restituisce un ID di sessione che verrà utilizzato per tutte le interazioni successive all'interno della stessa conversazione.

  1. Endpoint API di sessione: Identificare l'endpoint REST per la creazione di sessioni del servizio Generative AI Agents nella regione OCI.
  2. Processo APEX per la sessione: In una pagina APEX, creare un processo PL/SQL (ad esempio, un "Application Process" che viene eseguito all'inizio di ogni sessione utente o una "Dynamic Action" su caricamento pagina) per invocare l'API di creazione sessione.
    • URL dell'endpoint: `https://generativeaiagents..oci.oraclecloud.com/20231130/agents//sessions`
    • Metodo HTTP: `POST`
    • Payload JSON: `{"agentId": "ocid1.generativeaiagent."}`
    • Header di autenticazione: Utilizzare le credenziali web OCI.
  3. Memorizzazione dell'ID sessione: Dopo aver ricevuto la risposta, estrarre l'`sessionId` dal payload JSON. Questo ID dovrebbe essere memorizzato in una variabile di elemento APEX (ad esempio, `P1_SESSION_ID`) o in una variabile di sessione della sessione APEX per essere riutilizzato in tutte le chiamate di chat successive.

7. Creare e personalizzare il report classico per l'interfaccia di chat

L'interfaccia utente è cruciale per un'esperienza di chat efficace. In APEX, un "Classic Report" può essere personalizzato per visualizzare lo storico delle conversazioni tra l'utente e l'agente AI.

  1. Creazione della regione report: Aggiungere una nuova regione di tipo "Classic Report" a una pagina APEX.
  2. Definizione della fonte dati: La fonte dati per questo report sarà una collezione APEX (ad esempio, `APEX_COLLECTION`) che memorizzerà ogni messaggio scambiato, inclusi l'utente e la risposta dell'agente. Ogni riga della collezione potrebbe contenere campi come `MESSAGE_TYPE` (User/Agent), `MESSAGE_TEXT`, `TIMESTAMP`.
  3. Personalizzazione del layout:
    • Modificare il template del report per un aspetto "chat-like", ad esempio usando un template "Cards" o personalizzando un template "Standard" con CSS per bubble di chat.
    • Definire colonne per `MESSAGE_TEXT` e `TIMESTAMP`.
    • Applicare stili condizionali per differenziare i messaggi dell'utente da quelli dell'agente (es. allineamento a destra/sinistra, colori di sfondo diversi).
  4. Elementi di input: Aggiungere un elemento di tipo "Text Field" (es. `P1_USER_MESSAGE`) per l'input dell'utente e un pulsante (es. `P1_SEND_BUTTON`) per inviare il messaggio.

8. Creare azioni dinamiche per l'integrazione con gli agenti di intelligenza artificiale generativa OCI

Le "Dynamic Actions" in APEX sono il motore che orchestra l'interazione in tempo reale. Gestiranno l'invio dei messaggi dell'utente all'agente AI e la visualizzazione delle risposte.

  1. Azione dinamica per l'invio del messaggio:
    • Evento: "Click" del pulsante `P1_SEND_BUTTON` o "Key Press" sull'elemento `P1_USER_MESSAGE` per la chiave "Enter".
    • Azione 1: Aggiungi messaggio utente alla collezione:
      • Tipo: "Esegui codice PL/SQL".
      • Codice: `APEX_COLLECTION.ADD_MEMBER('CHAT_HISTORY', p_c001 => 'USER', p_c002 => :P1_USER_MESSAGE);`
      • Elementi da sottomettere: `P1_USER_MESSAGE`.
    • Azione 2: Chiama l'agente AI:
      • Tipo: "Esegui codice PL/SQL" (o "Esegui codice JavaScript" con una chiamata AJAX a un processo on-demand PL/SQL).
      • Codice PL/SQL (all'interno di un processo on-demand, richiamato da AJAX): 
                                DECLARE
                            l_response CLOB;
                            l_session_id VARCHAR2(256) := :P1_SESSION_ID;
                            l_user_message VARCHAR2(4000) := :P1_USER_MESSAGE;
                            l_agent_response VARCHAR2(4000);
                        BEGIN
                            -- Costruisci il payload JSON per la richiesta di chat
                            -- Invocare l'API REST di chat degli agenti OCI
                            l_response := APEX_WEB_SERVICE.MAKE_REST_REQUEST(
                                p_url => 'https://generativeaiagents..oci.oraclecloud.com/20231130/agents//sessions/' || l_session_id || '/chat',
                                p_http_method => 'POST',
                                p_body => '{ "message": "' || APEX_JSON.STRINGIFY(l_user_message) || '" }',
                                p_wallet_path => NULL, -- O se applicabile, il percorso del wallet
                                p_credential_static_id => 'OCI_GENAI_CREDENTIALS'
                            );

                            -- Parsifica la risposta JSON per estrarre il messaggio dell'agente
                            APEX_JSON.PARSE(l_response);
                            l_agent_response := APEX_JSON.GET_VARCHAR2('$.message.content');

                            -- Aggiungi il messaggio dell'agente alla collezione
                            APEX_COLLECTION.ADD_MEMBER('CHAT_HISTORY', p_c001 => 'AGENT', p_c002 => l_agent_response);

                            -- Aggiorna la regione del report classico e pulisci l'input
                            APEX_JAVASCRIPT.EXECUTE_JAVASCRIPT('apex.regions.your_report_region_static_id.refresh(); $s("P1_USER_MESSAGE", "");');
                        END;
      • Elementi da sottomettere: `P1_SESSION_ID`, `P1_USER_MESSAGE`.
      • Elementi da restituire: Nessuno (l'aggiornamento avviene tramite JavaScript).
    • Azione 3: Aggiorna report e pulisci input:
      • Tipo: "Aggiorna regione" (per la regione del report classico).
      • Tipo: "Imposta valore" (per l'elemento `P1_USER_MESSAGE`, impostandolo su NULL).

L'integrazione degli agenti di intelligenza artificiale generativa OCI con Oracle APEX apre nuove frontiere per lo sviluppo di applicazioni aziendali, offrendo un modo potente ed efficiente per infondere capacità conversazionali basate sull'IA nelle applicazioni a basso codice. Questo approccio non solo accelera lo sviluppo ma migliora anche significativamente l'esperienza utente, fornendo interazioni intelligenti e pertinenti basate sui dati aziendali.