RAG Tool HeatWave MySQL Guidelines for Generative AI Agents

Before using a HeatWave MySQL vector store as a data option for Generative AI Agents, ensure that you understand what's supported, and complete any required tasks.

Database Support

Generative AI Agents supports BYO vector embeddings from:

• HeatWave MySQL database systems. Any non-deprecated Innovation version.

• User-managed HeatWave MySQL databases running on OCI Compute instances

Cross-region and Cross-tenancy Support

When using Generative AI Agents in a hosted region, you can connect to a HeatWave MySQL database in:

• Another region within the same tenancy. Enable the connectivity by creating a database tools connection in the region where the agent service is available.
• Another tenancy. Enable the connectivity by creating a database tools connection in the tenancy where the agent service is available.

To set up the network settings, see Networking Requirements (Cross-region and Cross-tenancy database) in Step 3. Configure Networking and Security Requirements.

To create a connection, enter the connect string manually as described in Step 5. Create Database Tools Connections.

In addition to giving user access to all Generative AI Agents resources as described in Adding Policies Before You Can Use the Service, you need to create a dynamic group with access to Database Tools.

1. Create a dynamic group, and add the following matching rule.

   ALL {resource.type='genaiagent'}

   If you need help, see Creating a Dynamic Group.

2. Give permissions to the dynamic group.

   • Write the following policies, which can be used with the Default identity domain:

     allow dynamic-group <dynamic-group-name> 
     to read database-tools-family in compartment <compartment-name>
     
     allow dynamic-group <dynamic-group-name> to use database-tools-connections in compartment <compartment-name>
     

   • Use the following policies with an identity domain that's not Default, providing the Oracle Identity Cloud Service (IDCS) domain name and the dynamic group name:

     allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
     to read database-tools-family in compartment <compartment-name>
     
     allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
     to use database-tools-connections in compartment <compartment-name>
     

allow any-user to read database-tools-family in compartment <compartment-name> where any {request.principal.type='genaiagent'}

allow any-user to use database-tools-connections in compartment <compartment-name> where any {request.principal.type='genaiagent'}

Perform these tasks if you haven't already configured or created the required resources.

Networking Requirements

• Add the HeatWave MySQL database to the private subnet of a VCN.
• Set up the following properties for the private subnet's ingress rule:
  • Source Type: CIDR
  • Source CIDR: The VCN's IPv4 CIDR Block (such as 10.0.0.0/16)
  • IP Protocol: TCP
  • Source Port Range: All
  • Destination Port Range: 3306

Networking Requirements (Cross-region and Cross-tenancy database)

• Set up two VCNs with non-overlapping CIDRs. To configure the network settings, see Remote VCN Peering.
• In the HeatWave MySQL database's VCN, ensure that you add the ingress rule for the database tools connection's VCN CIDR to access the database port 3306.

Cross-region database example: You can connect to a database that's in a different region from where the Generative AI Agents service is running. For example:

• The agent service is running in tenancy A in the ORD region.

• The HeatWave MySQL database is deployed in the PHX region.

• To access the database, configure dynamic routing gateways (DRGs) in both regions and set up a database tools connection in ORD to connect to the database in PHX.

Cross-tenancy database example: You can connect to a database that's located in a different tenancy from the Generative AI Agents service. For example:

• The agent service is running in tenancy A in the ORD region.

• The HeatWave MySQL database is deployed in tenancy B in the PHX region.

• To access the database, configure dynamic routing gateways (DRGs) in both tenancies and set up a database tools connection in tenancy A (ORD region) to connect to the database in tenancy B (PHX region).

Cross-tenancy networking configuration applies regardless of whether the database service and the agent service are in the same region or in different regions.

Vault Security Requirements

A vault in OCI Vault is required to store secrets for the HeatWave MySQL database, such as the password to access the database.

Create the vault in the same compartment as the database tools connection. This applies to databases in the same region as the Generative AI Agents service, and to cross-region or cross-tenancy databases.

1. Create a vault.
2. Create a master encryption key.
3. In the vault, create a secret for the database password.

In the HeatWave MySQL database that you have created to use with Generative AI Agents, create a database table with certain required fields, and set up a database procedure that returns vector search results from queries.

Database Table

Create a table with the following fields:

Required Fields

• DOCID: An id assigned to each record or document
• BODY: The actual content that you want the agent to search
• VECTOR: The vector generated from an embedding model based on the body content

Optional Fields

• CHUNKID: An id for the chunked document, in case the document is larger than 512 tokens.
• URL: A URL reference for the content, if available.
• TITLE: The title of the body content
• PAGE_NUMBERS: The page numbers for the content, if available.

Tip

You can create text embeddings in OCI Generative AI.

Database Procedure

Set up a database procedure that can return vector search results from each query. Here are the requirements:

Input Parameters

• p_query: The query string
• top_k: Number of top results

Return Type

• JSON

Requirements

• The embedding model that you use for the function's query field must be the same as the embedding model that transforms the table's BODY content to vector embeddings.

• The function's return fields must match the table's required (DOCID, BODY and SCORE) and optional fields (CHUNKID, TITLE, and URL).

  The BODY content is processed by an embedding model to produce a VECTOR for each content. The function calculates the distances between the query vector and each VECTOR, returning the top_k rows. The SCORE field represents the distances between the query vector and the VECTOR from the BODY.

• If the function's return field names don't match the table field names, you must use aliases in the function.

Example

Here is an example of a database procedure:

-- Check if database exists, create it if not
CREATE DATABASE IF NOT EXISTS vector_store;
 
-- Switch to the database
USE vector_store;
 
-- Drop procedure if it exists (optional, for recreation)
DROP PROCEDURE IF EXISTS sample_search;
 
-- Create the procedure
CREATE PROCEDURE vector_store.sample_search(
  IN p_query TEXT,
  IN top_k INT UNSIGNED,
  OUT context JSON
)
BEGIN
  DECLARE i INT DEFAULT 0;
  DECLARE temp_json JSON DEFAULT JSON_ARRAY();
  -- Instead of using a temporary table, build the JSON directly
  SET i = 99; -- Start with highest scores
  -- Generate the top k results directly
  WHILE i >= (100 - top_k) AND i >= 0 DO
    SET temp_json = JSON_ARRAY_APPEND(temp_json, '$',
      JSON_OBJECT(
        'SCORE', FORMAT(i * 0.01, 2),
        'DOCID', i,
        'BODY', CONCAT('The sample text serves as a standardized sample for conducting comprehensive testing and performance evaluation in the environment.
Key Testing Objectives: Functionality verification, Performance assessment and System behavior analysis', i)
      )
    );
    SET i = i - 1;
  END WHILE;
  SET context = temp_json;
END

In OCI, use the Database Tools service to create reusable connections to a HeatWave MySQL database through a private endpoint.

Perform these tasks to establish a database connection.

1. Get the following information, if you don't already have the information that you need to create a connection.

   In the Console, open the navigation menu  and select Databases. Under HeatWave MySQL, select DB Systems.

   • Compartment in which the DB system is created
   • Name of the DB system
   • For a cross-region or cross-tenancy database: The private IP address and database port
   • Name of the vault secret for the database user's password

2. In the navigation menu, select Developer Services. Under Database Tools, select Connections to create a connection.

   1. Enter a name for the connection.
   2. Select the compartment in which to create the connection.

      We recommend creating the database tools connection in the same compartment as the vault secret for the database user's password.

   3. Use one of the following options to specify the connection information.
      • Click the Select database option to select a DB system and let the service retrieve the connection information.
        1. For Database cloud service, select MySQL Database.
        2. Select the compartment in which the DB system is created.
        3. Select the DB system name.
        4. Ensure that the Connection string field is automatically populated with the correct connection string. This is the DB system primary endpoint private IP address and database port. For example:

           mysql://10.0.1.156:3306

      • Use the Enter database information option for a cross-region or cross-tenancy database and enter the connection information manually.
        1. For Connection type, select MySQL.
        2. In Connection string, enter the connection string.

3. Complete the rest of the information to create a database tools connection to the HeatWave MySQL database through a private endpoint.

   1. Enter the username.

      Ensure that the database user has the necessary permissions, and can run the database procedure that's prepared in Step 4. Set Up a Database Table and a Procedure.

   2. Select the compartment in which you created the vault secret for the database user's password.

      If you don't have a vault secret, select Create password secret and create a vault. Then create a secret to store the password in the vault. We recommend creating the vault and secret in the same compartment as the database tools connection.

   3. Enable the Access database via a private network option and click Select private endpoint. Then select the compartment and the private endpoint to the database.

      If you don't have a private endpoint, select Create private endpoint and create an endpoint using the same VCN and private subnet as the database.