Building Your First Generative AI Agent with Oracle APEX - Getting Started

-

 


Introduction

Generative AI is transforming how we build applications, and Oracle APEX provides an excellent low-code platform to quickly develop AI-powered solutions. In this first part of our series, I'll walk you through the complete process of setting up your environment and creating your first AI agent using Oracle APEX and Oracle Cloud Infrastructure (OCI) Generative AI Service.

By the end of this tutorial, you'll have a working AI chatbot that can answer questions and engage in conversations.

Prerequisites

Before we begin, ensure you have:

  • An Oracle Cloud Infrastructure (OCI) account with appropriate permissions
  • Access to Oracle APEX workspace (version 23.1 or later recommended)
  • Basic understanding of APEX application development
  • Familiarity with REST API concepts

Step 1: Setting Up Oracle Cloud Infrastructure

1.1 Create an OCI Compartment

First, let's organize our resources by creating a dedicated compartment:

  1. Log in to your OCI Console (https://cloud.oracle.com)
  2. Navigate to Identity & Security → Compartments
  3. Click Create Compartment
  4. Fill in the details:
    • Name: GenAI-APEX-Demo
    • Description: Compartment for Generative AI APEX applications
    • Parent Compartment: Select your root or preferred compartment
  5. Click Create Compartment

1.2 Enable OCI Generative AI Service

  1. From the OCI Console, open the navigation menu
  2. Go to Analytics & AI → Generative AI
  3. Ensure your region supports Generative AI (currently available in US Midwest - Chicago, Germany - Frankfurt, and UK South - London)
  4. If needed, switch to a supported region using the region selector at the top right

1.3 Create API Keys for Authentication

  1. Click on your profile icon (top right) → User Settings
  2. Scroll down to Resources → API Keys
  3. Click Add API Key
  4. Select Generate API Key Pair
  5. Click Download Private Key and save it securely (you'll need this later)
  6. Click Download Public Key (optional, for backup)
  7. Click Add
  8. Copy the configuration file preview - you'll need:
    • User OCID
    • Tenancy OCID
    • Fingerprint
    • Region

Important: Keep your private key secure and never commit it to version control!

1.4 Create a Policy for Generative AI Access

  1. Navigate to Identity & Security → Policies
  2. Select your GenAI-APEX-Demo compartment
  3. Click Create Policy
  4. Enter the following:
    • Name: GenAI-APEX-Policy
    • Description: Policy to allow Generative AI service usage
    • Compartment: Select your compartment
  5. Toggle to Show manual editor and add:
Allow group <your-user-group> to manage generative-ai-family in compartment GenAI-APEX-Demo Allow group <your-user-group> to read secret-family in compartment GenAI-APEX-Demo

6.Click Create


Step 2: Configuring OCI Generative AI Service

2.1 Test the Generative AI Playground

Before integrating with APEX, let's verify the service is working:

  1. Navigate to Analytics & AI → Generative AI
  2. Click on Playgrounds → Chat
  3. Try sending a test message like "What is Oracle APEX?"
  4. If you receive a response, the service is working correctly

2.2 Identify Your Model OCID

  1. In the Generative AI console, go to Models
  2. Find the model you want to use (e.g., cohere.command-r-plus or meta.llama-3.1-70b-instruct)
  3. Copy the OCID of the model - you'll need this for API calls

Example model endpoint:

https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat

Step 3: Setting Up Oracle APEX Application

3.1 Create a New APEX Application

  1. Log in to your APEX workspace
  2. Click App Builder → Create
  3. Select New Application
  4. Configure:
    • Name: AI Agent Demo
    • Appearance: Choose your preferred theme (Universal Theme 42 recommended)
  5. Add a blank page:
    • Page Name: AI Chatbot
    • Page Type: Blank Page
  6. Click Create Application

3.2 Store API Credentials Securely

Never hardcode API keys! Use APEX credentials store:

  1. Go to Shared Components → Web Credentials
  2. Click Create
  3. Configure:
    • Name: OCI_GenAI_Credentials
    • Authentication Type: OCI Native Authentication
    • OCI User ID: Paste your User OCID from Step 1.3
    • OCI Private Key: Paste the contents of your downloaded private key file
    • OCI Tenancy ID: Paste your Tenancy OCID
    • OCI Public Key Fingerprint: Paste your fingerprint
  4. Click Create

3.3 Create Application Items for Configuration

  1. Go to Shared Components → Application Items
  2. Create the following items:

Item 1:

  • Name: AI_MODEL_OCID
  • Initial Value: Your model OCID from Step 2.2

Item 2:

  • Name: AI_ENDPOINT
  • Initial Value: https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat

Item 3:

  • Name: AI_COMPARTMENT_ID
  • Initial Value: Your compartment OCID

Step 4: Building the REST Integration

4.1 Create REST Data Source

  1. Go to Shared Components → REST Data Sources
  2. Click Create
  3. Choose From Scratch
  4. Configure the REST Data Source:

General Settings:

  • Name: OCI_GenAI_Chat
  • URL Endpoint: https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat
  • Authentication Type: OCI Native Authentication
  • Credentials: Select OCI_GenAI_Credentials
  1. Click Next

4.2 Configure the POST Operation

  1. On the Operations step, click Add Operation
  2. Configure:
    • URL Pattern: (leave empty for POST to base URL)
    • HTTP Method: POST
    • Request Body Type: JSON
  3. Add a sample request body:
{ "compartmentId": "ocid1.compartment.oc1...", "servingMode": { "servingType": "ON_DEMAND", "modelId": "ocid1.generativeaimodel.oc1.us-chicago-1..." }, "chatRequest": { "message": "Hello, who are you?", "maxTokens": 500, "temperature": 0.7, "frequencyPenalty": 0, "presencePenalty": 0, "topP": 0.75, "topK": 0 } }
  1. Click Discover to automatically detect response structure
  2. Click Create REST Data Source

Step 5: Creating the Chat Interface

5.1 Design the Page Layout

  1. Navigate to your AI Chatbot page
  2. Create a new Region:
    • Type: Static Content
    • Title: AI Assistant
    • Template: Standard

5.2 Add Chat Input Elements

Add the following page items:

Item 1: User Message Input

  • Name: P1_USER_MESSAGE
  • Type: Textarea
  • Label: Your Message
  • Placeholder: Type your message here...
  • Settings:
    • Width: 100%
    • Rows: 3

Item 2: Chat History Display

  • Name: P1_CHAT_HISTORY
  • Type: Display Only
  • Label: Conversation
  • Format: HTML Expression
  • Settings:
    • Add custom CSS classes: chat-container

Item 3: Send Button

  • Create a Button:
    • Name: SEND_MESSAGE
    • Label: Send
    • Position: Below P1_USER_MESSAGE
    • Action: Submit Page

Step 6: Implementing the AI Logic

6.1 Create a PL/SQL Process

  1. Create a new Process on your page
  2. Configure:
    • Name: Call_GenAI_Service
    • Type: Execute Code
    • When Button Pressed: SEND_MESSAGE
  3. Add the following PL/SQL code:
DECLARE
    l_request_body    CLOB;
    l_response        CLOB;
    l_ai_response     VARCHAR2(32767);
    l_chat_history    CLOB;
BEGIN
    -- Build the request body
    l_request_body := json_object(
        'compartmentId' value :AI_COMPARTMENT_ID,
        'servingMode' value json_object(
            'servingType' value 'ON_DEMAND',
            'modelId' value :AI_MODEL_OCID
        ),
        'chatRequest' value json_object(
            'message' value :P1_USER_MESSAGE,
            'maxTokens' value 500,
            'temperature' value 0.7,
            'topP' value 0.75,
            'frequencyPenalty' value 0,
            'presencePenalty' value 0,
            'topK' value 0
        )
    );
    
    -- Make the API call
    apex_web_service.g_request_headers.DELETE;
    apex_web_service.g_request_headers(1).name := 'Content-Type';
    apex_web_service.g_request_headers(1).value := 'application/json';
    
    l_response := apex_web_service.make_rest_request(
        p_url => :AI_ENDPOINT,
        p_http_method => 'POST',
        p_body => l_request_body,
        p_credential_static_id => 'OCI_GenAI_Credentials'
    );
    
    -- Parse the response
    apex_json.parse(l_response);
    l_ai_response := apex_json.get_varchar2(p_path => 'chatResponse.text');
    
    -- Update chat history
    l_chat_history := :P1_CHAT_HISTORY;
    l_chat_history := l_chat_history || 
        '<div class="user-message"><strong>You:</strong> ' || 
        APEX_ESCAPE.HTML(:P1_USER_MESSAGE) || '</div>' ||
        '<div class="ai-message"><strong>AI:</strong> ' || 
        APEX_ESCAPE.HTML(l_ai_response) || '</div>';
    
    :P1_CHAT_HISTORY := l_chat_history;
    :P1_USER_MESSAGE := NULL;
    
EXCEPTION
    WHEN OTHERS THEN
        apex_error.add_error(
            p_message => 'Error calling AI service: ' || SQLERRM,
            p_display_location => apex_error.c_inline_in_notification
        );
END;

6.2 Add Custom CSS

  1. Navigate to Page Designer → Page Properties
  2. Under CSS → Inline, add:
.chat-container {
    max-height: 500px;
    overflow-y: auto;
    border: 1px solid #ddd;
    padding: 15px;
    background-color: #f9f9f9;
    border-radius: 8px;
}

.user-message {
    background-color: #e3f2fd;
    padding: 10px;
    margin: 10px 0;
    border-radius: 8px;
    border-left: 4px solid #2196F3;
}

.ai-message {
    background-color: #f1f8e9;
    padding: 10px;
    margin: 10px 0;
    border-radius: 8px;
    border-left: 4px solid #8bc34a;
}

Step 7: Testing Your AI Agent

7.1 Run the Application

  1. Click Save and Run Page
  2. Type a test message: "What is Oracle APEX?"
  3. Click Send
  4. You should see:
    • Your message displayed in blue
    • The AI's response displayed in green

7.2 Troubleshooting Common Issues

Issue 1: Authentication Error

  • Verify your API keys are correctly entered in Web Credentials
  • Check that the private key includes the BEGIN/END markers
  • Ensure your user has proper permissions in OCI

Issue 2: Model Not Found

  • Verify the model OCID is correct
  • Check that you're using a supported region
  • Ensure the model is available in your compartment

Issue 3: No Response

  • Check the APEX Debug mode to see the actual API response
  • Verify your compartment ID is correct
  • Check OCI service limits and quotas

Step 8: Next Steps and Enhancements

Congratulations! You've built your first AI agent with Oracle APEX. Here are some immediate improvements you can make:

  1. Add Session Management: Store conversation history in a database table
  2. Implement Streaming: Show responses as they're generated
  3. Add Error Handling: Display user-friendly error messages
  4. Style Improvements: Enhance the UI with better formatting

What's Coming in Blog 2

In the next part of this series, we'll dive deeper into creating sophisticated conversational interfaces including:

  • Building dynamic chat bubbles with timestamps
  • Implementing conversation memory and context
  • Adding typing indicators and smooth animations
  • Supporting multi-turn conversations with context retention

Conclusion

You've successfully set up OCI Generative AI with Oracle APEX and created a working AI chatbot. This foundation will serve you well as we explore more advanced features in the upcoming blogs.

The combination of Oracle APEX's rapid development capabilities and OCI's powerful Generative AI services enables you to build sophisticated AI applications without extensive coding.

Resources:

Comments

Post a Comment

Popular posts from this blog

Setting Up Monitoring and Alerts in OCI for Your Resources

-
Image
  Oracle Cloud Infrastructure (OCI) provides powerful Monitoring and Alarms features to help you gain visibility into the health and performance of your cloud resources. In this blog post, we’ll walk through the step-by-step process of setting up monitoring and alerts for CPU, Memory, and other important metrics using OCI’s native tools. ✅ Whether you’re managing Compute Instances, Autonomous Databases, Load Balancers, or other services, OCI Monitoring helps you stay ahead of performance issues by automatically collecting and analyzing metrics. 🎯 What We Will Cover Understanding OCI Monitoring and Metrics Enabling Monitoring for Resources Setting Up Alarms (CPU, Memory, etc.) Viewing Metrics in the OCI Console Notifications Using OCI Notifications Service Bonus: Monitoring Using CLI & SDK (Optional for automation)   🧠 1. What is OCI Monitoring? OCI Monitoring allows you to collect, view, and analyze metrics for your cloud resources in near real-...
Read more
-
Image
  🐚 How to Use Oracle Cloud Shell Like a Pro Introduction Oracle Cloud Shell is a browser-based terminal pre-authenticated with your Oracle Cloud account. It comes with a rich set of tools to help you manage and automate your OCI resources—no setup needed. In this blog, we’ll walk through everything from launching Cloud Shell to using advanced tools like oci-cli , Git, and Terraform—all directly from your browser. 🧰 What Is Oracle Cloud Shell? Web-based shell environment Persistent 5GB storage in $HOME/cloudshell Pre-installed tools : OCI CLI Git Terraform Kubectl Helm Python, Java, Node.js Text editors (nano, vi) Auto-authenticated : No need to configure your API keys. 🟢 How to Launch Oracle Cloud Shell Log in to Oracle Cloud Console . Click the Cloud Shell icon (top-right corner, looks like >_ ). The shell will open in the lower panel—ready to use. ⚙️ Exploring the Environment Code : # Check current user whoami # List home d...
Read more

Introduction to Oracle Vector Search – Concepts, Requirements & Use Cases

-
Image
  Title: Unlocking the Power of Oracle Vector Search: Concepts, Requirements, and Real-World Use Cases Introduction: In today’s AI-driven world, traditional keyword-based search techniques are no longer sufficient for applications like image recognition, recommendation engines, or natural language search. This is where vector search steps in — enabling machines to find semantically similar data even when exact keywords don't match. Oracle has embraced this next-gen capability with native vector search support in Oracle Database 23ai , making it possible to run efficient similarity searches — even on BLOB-based image embeddings . This blog kicks off our 5-part series where we explore Oracle Vector Search , especially focusing on handling images as BLOBs and converting them into meaningful vector embeddings for AI-powered search. What is Vector Search? Vector search, also known as nearest neighbor search , enables finding items based on similarity in a high-dimensional space....
Read more