Oracle Cloud Infrastructure Documentation

Oracle Database Guidelines for Generative AI Agents

You can bring your own (BYO) vector embeddings from an Oracle Database version 23ai to OCI Generative AI Agents.

To make data in Object Storage available to Generative AI Agents, see Object Storage Guidelines in Generative AI Agents. To make available BYO ingested and indexed OCI Search with OpenSearch data for the agents to use, see OCI Search with OpenSearch Guidelines for Generative AI Agents.

This topic describes support information, prerequisite tasks, and guidelines for using Oracle Database 23ai as a data option for Generative AI Agents. The information provided assumes that you're familiar with virtual cloud networks (VCNs) and subnets, Oracle Database 23ai, and the Database Tools service.

Step 1. Review Database Support Information

Before using an Oracle Database version 23ai vector store as a data option for Generative AI Agents, ensure that you understand what's supported, and complete any required tasks.

Database Types

Generative AI Agents supports BYO vector embeddings from:

  • Oracle Base Database 23ai: The database can be configured on a private network. See Create a DB System.

  • Oracle Autonomous Database 23ai of the following network access types only:

    • Private endpoint access only: Mutual TLS (mTLS) authentication can be enabled to authenticate connections to your database. Select the checkbox Require mutual TLS (mTLS) authentication to enable mTLS authentication.

    • Secure access from everywhere: mTLS authentication is enabled by default and is required.

    See Create an Autonomous Database Instance.

Autonomous Databases Enabled for mTLS Authentication

If the autonomous database is enabled for mTLS authentication, you must download the wallet, create a wallet password, and extract a file from the wallet. See Wallet Security Requirements in Step 3. Configure Networking and Security Requirements.

Cross-region and Cross-tenancy Database Support

Cross-region and cross-tenancy database support is only available for Oracle Database 23ai with private network access. This includes Oracle Base Database and Oracle Autonomous Database that's configured by the network access type Private endpoint access only. Autonomous databases with public access are not supported.

When using Generative AI Agents in a hosted region, you can connect to a private access database that resides 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.

Step 2. Add Dynamic Group and Policies

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 vault secrets and 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 by writing the following policies.

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

allow dynamic-group <dynamic-group-name> 
to read secret-bundle in compartment <compartment-name>
Step 3. Configure Networking and Security Requirements

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

Networking Requirements
  • Add the database to the private subnet of a VCN.
  • Set up the following properties for the 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: 1521-1522
Networking Requirements (Cross-region and Cross-tenancy database)

The following requirements are only applicable to Oracle Database 23ai with private network access. This includes Oracle Base Database and Oracle Autonomous Database that's configured by the network access type Private endpoint access only. Autonomous databases with public access are not supported.

Network settings

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

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 Oracle Base Database or Oracle Autonomous Database with private network access is deployed in the PHX region.

  • To access the private 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 Oracle Base Database or Oracle Autonomous Database with private network access is deployed in tenancy B in the PHX region.

  • To access the private 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 database, such as the password to the database. Create the vault in the same compartment as the database.

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

If the autonomous database is enabled for mTLS authentication, perform the following tasks:

  1. Download the wallet and create a wallet password. See Download Client Credentials (Wallets).
  2. From the downloaded wallet zip, extract the file ewallet.p12 and put it aside. You need the PKCS#12 wallet to create the database tools connection.
Step 4. Set Up a Database Table and a Function

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

Database Table
Create an Oracle Database 23ai 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 Function

A function is a subprogram that can take parameters and return a value. You need to set up a database function 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

  • SYS_REFCURSOR

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 function:

create or replace FUNCTION RETRIEVAL_FUNC (p_query IN VARCHAR2,top_k IN NUMBER) RETURN SYS_REFCURSOR IS
    v_results SYS_REFCURSOR;
    query_vec VECTOR;
BEGIN
    query_vec := dbms_vector.utl_to_embedding(
        p_query,
        json('{
            "provider": "OCIGenAI",
            "credential_name": "OCI_VECTOR_CREDENTIAL",
            "url": "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/embedText",
            "model": "cohere.embed-english-v3.0"
        }')
    );

    OPEN v_results FOR
        select l.id as DOCID, lv.chunk_id as CHUNKID, l.file_name as TITLE, 
        'https://objectstorage.us-chicago-1.oraclecloud.com/n/{namespace}/b/{bucket_name}/o/' || l.file_name as URL,
        lv.chunk_txt as BODY, vector_distance(embed_vector, query_vec) AS SCORE
        from legislation_vector lv, legislation l
        where l.id = lv.id
        order by SCORE 
        fetch first top_k rows only;

    RETURN v_results;
END;
Step 5. Create Database Tools Connections

You can create reusable connections to an Oracle database in OCI by using the Database Tools service.

Follow these guidelines to create a connection for your database.

Guidelines for Oracle Base Database 23ai Connection

Generative AI Agents can access an Oracle Base Database 23ai through a private endpoint. Perform these tasks to establish the database connection.

  1. Gather the following information:

    In the Console, open the navigation menu  and select Oracle Database, then select Oracle Base Database Service. Select the database system name and then select the database name. Copy the following properties to use for the connection information in the next step:

    • Database System
    • Database
    • Database Home

    • On the left side, select Pluggable Databases and select the pluggable database name. Select PDB connection and copy the connection string with the Long format.

      Example connection string with a long format:

      (DESCRIPTION=(CONNECT_TIMEOUT=5)(TRANSPORT_CONNECT_TIMEOUT=3)(RETRY_COUNT=3)
(ADDRESS_LIST=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=TCP)(HOST=10.0.0.62)(PORT=1521)))
(CONNECT_DATA=(SERVICE_NAME=xxx_pdb1.xxx.dbsvcn.oraclevcn.com)))

  2. In Database Tools, create a connection using one of the following options:

    • Use the Select database option to select a database.
      1. Select Oracle Base Database.
      2. Select the database system, database home, and database.
      3. Select the pluggable database.
    • Use the Enter database information option for a cross-region or cross-tenancy database and enter the connection information manually. For Connection type, select Oracle Database.

  3. Complete the rest of the information with the following properties:

    • Enter the username and select the role for the user.

      Ensure that the database user has the necessary permissions, can run the database function that was prepared in Step 4. Set Up a Database Table and a Function, and is assigned an appropriate role. For example, for the SYS user, assign the SYSDBA role.

    • For User password secret, select the secret if it's already created. Otherwise, select Create password secret and create a secret to store the password in the vault that you have created.
    • For Connection string, paste the long format for the pluggable database that you copied in step 1 of this procedure.

      For a cross-region or cross-tenancy database, enter the connection string.

    • Select the Access database via a private network checkbox.
    • For Private endpoint, do one of the following:
      • Click Select private endpoint and select the endpoint.
      • Select Create private endpoint and create the endpoint. For Subnet, select the private subnet of the database. Ensure that you create the private endpoint using the same VCN and subnet as the database.
    • For Wallet format, select None to create a connection without mutual TLS (mTLS) authentication.
Guidelines for Autonomous Database 23ai Connection

Generative AI Agents can access an Autonomous Database 23ai through a private endpoint with a connection that's set up for mutual TLS (mTLS) authentication. Perform these tasks to establish a database connection.

  1. Gather the following information:

    In the Console, open the navigation menu . Select Oracle Database and then select Autonomous Database. Select the database. On the database details page, copy the following properties to use for the connection information in the next step:

    • Database name
    • (For Private endpoint access only network access) Under the Network section:
      • Private endpoint IP
      • Private endpoint URL
    • Select Database connection and do the following:
      • In the list of TNS names, find the TNS name that ends with _high, and copy its connection string.
      • Only for a database that requires Mutual TLS (mTLS) authentication: Download the wallet. See Wallet Security Requirements in Step 3. Configure Networking and Security Requirements.

  2. In Database Tools, create a connection using one of the following options:

    • Use the Select database option to select a database.
      1. Select Oracle Autonomous Database.
      2. Select the database.
    • Use the Enter database information option for a cross-region or cross-tenancy database and enter the connection string manually. For Connection type, select Oracle Database.

  3. Complete the rest of the information with the following properties:

    • For Username, enter the user that has the necessary permissions and can run the database function that was prepared in Step 4. Set Up a Database Table and a Function.
    • For User password secret, select the secret if it's already created. Otherwise, select Create password secret and create a secret to store the password in the vault that you have created.
    • For Connection string, paste the connection string that ends with _high, the string that you copied from the Database connection section of the database details page.
      Then, depending on the database type, update the string as follows:
      • Private access database: Reduce retry_count from 20 to 3, and replace the host private endpoint URL with the private endpoint IP address.

        Connection string example:

        (description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1522)
(host=<private-endpoint-URL>)(connect_data=(service_name=xxx_high.adb.oraclecloud.com))
(security=(ssl_server_dn_match=no)))

        Updated connection string example:

        (description= (retry_count=3)(retry_delay=3)(address=(protocol=tcps)(port=1522)
(host=<private-endpoint-IP>)(connect_data=(service_name=xxx_high.adb.oraclecloud.com))
(security=(ssl_server_dn_match=no)))

      • Public access database: Reduce retry_count from 20 to 3.

        Updated connection string example:

        (description= (retry_count=3)(retry_delay=3)(address=(protocol=tcps)(port=1522)
(host=<name>)(connect_data=(service_name=xxx_high.adb.oraclecloud.com))
(security=(ssl_server_dn_match=yes)))
    • (For Private endpoint access only network access) Select the checkbox for Access database via a private network. Then select the private endpoint, or select Create private endpoint to create an endpoint, making sure to use the same VCN and private subnet as the database.
    • For Wallet format:
      • For a database that's not enabled for mTLS authentication, select None.
      • For a database that's enabled for mTLS authentication, select PKCS#12 wallet(e.g., ewallet.p12). Then create the wallet content secret and the wallet password secret, or select them if you have already created the secrets.