NL2SQL Data Retrieval Agent

Author: sandeepkhot

autonomous-ai-agents/README.md

@@ -1,9 +1,9 @@
 
-# Select AI Agents on Oracle Autonomous Database
+# Select AI Agents on Oracle Autonomous AI Database
 
 ## Overview
 
-This repository provides a **generic, extensible framework for building Select AI Agents on Oracle Autonomous Database** using the **Select AI Agent framework**.
+This repository provides a **generic, extensible framework for building Select AI Agents on Oracle Autonomous AI Database** using the **Select AI Agent framework**.
 
 Select AI Agents enable natural language interactions with enterprise data by combining large language models (LLMs), database-resident tools, and orchestration logic directly inside Oracle Database. Agents can reason over user input, invoke tools, and return structured, explainable results — all while keeping data governance, security, and execution within the database.
 
@@ -13,20 +13,20 @@ The agents in this repository are **generic Select AI agents**. While some examp
 
 ## What is a Select AI Agent?
 
-Select AI Agents are part of the Oracle Autonomous Database Select AI framework. A Select AI Agent:
+Select AI Agents are part of the Oracle Autonomous AI Database Select AI framework. A Select AI Agent:
 
 - Accepts natural language input from users
 - Uses an LLM to reason about the request
 - Invokes database-resident tools (PL/SQL functions)
 - Executes logic securely inside the database
-- Returns structured and auditable responses
+- Returns structured responses
 
 Key characteristics of the Select AI Agent framework include:
 
-- Native integration with Oracle Database
+- Native integration with Oracle Autonomous AI Database
 - Tool execution through PL/SQL
 - Support for tasks, agents, and teams
-- Centralized governance and auditing
+- Centralized governance and monitoring
 - Flexibility to build domain-specific or generic agents
 
 For full details, refer to the official documentation:
@@ -103,7 +103,7 @@ This repository is intended for:
 - Data engineers
 - Architects
 - Platform teams
-- AI practitioners working with Oracle Database
+- AI practitioners working with Oracle Autonomous AI Database
 
 Anyone looking to build secure, database-native AI agents using Select AI can use this repository as a starting point.
 
@@ -112,5 +112,4 @@ Anyone looking to build secure, database-native AI agents using Select AI can us
 ## License
 
 This project is licensed under the **Universal Permissive License (UPL), Version 1.0**.
-
 See: https://oss.oracle.com/licenses/upl/

autonomous-ai-agents/nl2sql_data_retrieval/README.md

@@ -1,6 +1,6 @@
-# Select AI - NL2SQL Data Retrieval Agent for Oracle Autonomous Database
+# Select AI - NL2SQL Data Retrieval Agent for Oracle Autonomous AI Database
 
-## Why This Select AI - NL2SQL Agent Is Better Than Plain Select AI NL2SQL
+## How the NL2SQL agent improves upon Select AI NL2SQL
 
 Oracle Select AI already provides Natural Language to SQL (NL2SQL), but **real-world data retrieval often fails** due to:
 
@@ -34,7 +34,7 @@ into a **single autonomous agent workflow**.
 | Chart generation | ❌ | ✅ |
 | Config-driven & extensible | ❌ | ✅ |
 
-> **Result:** Higher accuracy, fewer hallucinations, safer SQL, and richer analytical answers.
+> **Result:** Higher accuracy, fewer hallucinations, accurate SQL, and richer analytical answers.
 
 ---
 
@@ -56,7 +56,7 @@ Agent Reasoning
 Final Verified Answer + Sources
 ```
 
-The agent dynamically selects tools, retries intelligently, and produces **auditable and explainable outputs**.
+The agent dynamically selects tools, retries intelligently, and produces **explainable outputs**.
 
 ---
 
@@ -66,7 +66,7 @@ The agent dynamically selects tools, retries intelligently, and produces **audit
 .
 ├── nl2sql_data_retrieval_tools.sql
 │   ├── PL/SQL utility functions
-│   ├── OCI Vault integration
+│   ├── OCI Vault integration for Websearch credentials
 │   ├── Web search enablement
 │   └── AI tool registration
 │
@@ -83,10 +83,10 @@ The agent dynamically selects tools, retries intelligently, and produces **audit
 
 ##  Prerequisites
 
-- Oracle Autonomous Database
+- Oracle Autonomous AI Database
 - Select AI enabled
-- OCI Vault configured (Option for websearch)
-- Google Custom Search API enabled (Option for websearch)
+- OCI Vault configured (Optional for websearch)
+- Google Custom Search API enabled (Optional for websearch)
 - Run as ADMIN 
 
 ---
@@ -126,6 +126,12 @@ Run as ADMIN (or privileged user):
 ```sql
 sqlplus admin@db @nl2sql_data_retrieval_tools.sql
 ```
+### Input Parameters required to run.
+- Target schema name (Schema where to the agent team needs to be installed)
+- Cloud Config Parameters required for Websearch (This is mandatory to enable Websearch)
+  - Google Search API Keys needs to be stored in OCI Vault
+  - Vault Secret OCID's.
+  - OCI Region name where Vault is created.
 
 ### Example Configuration JSON
 
@@ -134,8 +140,7 @@ sqlplus admin@db @nl2sql_data_retrieval_tools.sql
   "credential_name": "OCI_CRED",
   "vault_region": "eu-frankfurt-1",
   "api_key_vault_secret_ocid": "ocid1.vaultsecret.oc1..aaaa",
-  "cxid_vault_secret_ocid": "ocid1.vaultsecret.oc1..bbbb",
-  "ai_profile": "MY_AI_PROFILE"
+  "cxid_vault_secret_ocid": "ocid1.vaultsecret.oc1..bbbb"
 }
 ```
 
@@ -144,14 +149,14 @@ sqlplus admin@db @nl2sql_data_retrieval_tools.sql
 - Grants required DBMS_CLOUD and Select AI privileges  
 - Creates `SELECTAI_AGENT_CONFIG`  
 - Installs `NL2SQL_DATA_RETRIEVAL_FUNCTIONS`  
-- Registers all AI agent tools  
+- Registers all AI agent tools.
 
 ---
 
 ##  Installed Tools Explained
 
 ### 1️⃣ SQL_TOOL
-**Purpose:** Generate SQL from natural language and execute it safely.
+**Purpose:** Generate SQL from natural language and run it safely.
 
 **Fail-safe behavior:**
 - SQL generation failure → feedback returned to the LLM  
@@ -214,17 +219,18 @@ Run:
 sqlplus admin@db @nl2sql_data_retrieval_agent.sql
 ```
 
-### Prompts
-- Target schema name  
-- AI Profile name  
+### Input Parameters required to run.
+- Target schema name (Schema where to the agent team needs to be installed)
+- AI Profile name (Select AI Profile name that needs to be used with the Agent)
+
 
 ### Objects Created
 
 | Object | Name |
-|------|------|
-| Task | NL2SQL_DATA_RETRIEVAL_TASK |
+|-------|------|
+| Task  | NL2SQL_DATA_RETRIEVAL_TASK  |
 | Agent | NL2SQL_DATA_RETRIEVAL_AGENT |
-| Team | NL2SQL_DATA_RETRIEVAL_TEAM |
+| Team  | NL2SQL_DATA_RETRIEVAL_TEAM  |
 
 ---
 
@@ -252,7 +258,6 @@ Specialize agents using tasks.**
 |----|-----------|--------|
 | Data Retrieval Team | All tools | General analytics |
 | Finance Analytics Team | SQL + RANGE | Financial reporting |
-| Metadata Explorer Team | DISTINCT | Schema exploration |
 | Research Agent Team | WEBSEARCH | External intelligence |
 | Visualization Team | SQL + CHART | Dashboards & insights |
 
@@ -262,24 +267,22 @@ Specialize agents using tasks.**
 - Agents bind AI profiles  
 - Teams orchestrate workflows  
 
----
-
-## Safe Re-Execution
+### Example prompts
+After creating the NL2SQL Data Retrieval Agent team, you can interact with it using prompts such as:
 
-All scripts are **idempotent**:
-- Tools are dropped and recreated  
-- Tasks, agents, and teams are refreshed  
-- Secrets remain in OCI Vault  
+- “How can you help?”
+- Ask questions related to the database tables associated with the selected profile.
+- To generate visualizations, explicitly mention the chart type, for example:
+  “Generate a bar chart for the result.” (any supported chart type can be used)
+- To perform a web search, ask relevant questions after configuring the required credentials.
 
 ---
 
 ##  Best Practices
 
 - Use `DISTINCT_VALUES_CHECK` before filtering text columns  
-- Use `RANGE_VALUES_CHECK` for DATE and NUMBER columns  
-- Always verify web content with `GET_URL_CONTENT`  
-- Maintain separate AI profiles per environment  
-- Rotate Vault secrets without code changes  
+- Use `RANGE_VALUES_CHECK` for DATE and NUMBER columns    
+- Maintain separate AI profiles per environment   
 
 ---
 
@@ -290,7 +293,7 @@ https://oss.oracle.com/licenses/upl/
 
 ---
 
-## ✨ Final Thought
+## ✨ Final Thoughts
 
 This NL2SQL Data Retrieval Agent elevates Select AI from a **SQL generator** to a **true autonomous data analyst** — capable of reasoning, validating, retrying, enriching, and visualizing data with confidence.
 

autonomous-ai-agents/oci_autonomous_database/README.md

@@ -6,7 +6,7 @@ The **Select AI - OCI Autonomous Database AI Agent** enables natural-language–
 
 Unlike traditional scripts or consoles, this agent allows users to:
 - Provision and manage Autonomous Databases conversationally
-- Safely execute lifecycle operations with confirmations
+- Run lifecycle operations with confirmations
 - Discover OCI resources dynamically (regions, compartments, databases)
 - Automate complex OCI workflows through reusable AI tools
 
@@ -23,7 +23,6 @@ Compared to manual OCI operations or simple chat-based automation, this agent:
 - Requires **explicit confirmation for destructive actions**
 - Uses **OCI-native APIs** through PL/SQL wrappers
 - Produces **human-readable outputs**, not raw JSON dumps
-- Is **idempotent and safe to re-run**
 
 ---
 
@@ -85,6 +84,12 @@ Run as ADMIN (or privileged user):
 sqlplus admin@db @oci_autonomous_database_tools.sql
 ```
 
+### Input Parameters required to run.
+- Target schema name (Schema where to the agent team needs to be installed)
+- Cloud Config Parameters.
+  - OCI Credentials - Required to access to Object Storage buckets.
+  - Compartment Name 
+  
 ### Optional Configuration JSON
 
 ```json
@@ -147,16 +152,16 @@ Run:
 sqlplus admin@db @oci_autonomous_database_agent.sql
 ```
 
-### Prompts
-- Target schema name
-- AI Profile name
+### Input Parameters required to run.
+- Target schema name (Schema where to the agent team needs to be installed)
+- AI Profile name (Select AI Profile name that needs to be used with the Agent)
 
 ### Objects Created
 
 | Object | Name |
 |------|------|
 | Task | OCI_AUTONOMOUS_DATABASE_TASKS |
-| Agent | OCI_AUTONOMOUS_DATABASE_ADVISOR |
+| Agent| OCI_AUTONOMOUS_DATABASE_ADVISOR |
 | Team | OCI_AUTONOMOUS_DATABASE_TEAM |
 
 ---
@@ -169,7 +174,6 @@ The task enforces:
 - Clarifying questions for incomplete input
 - Mandatory confirmation for destructive actions
 - Human-readable formatting of OCI outputs
-- Safe automation of OCI operations
 
 ---
 
@@ -189,15 +193,6 @@ Bind profiles at agent level.**
 
 ---
 
-##  Safe Re-Execution
-
-All scripts are **safe to re-run**:
-- Tasks, agents, and teams are dropped and recreated
-- OCI configuration is preserved
-- No duplicate OCI resources are created accidentally
-
----
-
 ##  Best Practices
 
 - Always use confirmation for destructive actions
@@ -208,16 +203,55 @@ All scripts are **safe to re-run**:
 
 ---
 
+## Example Prompts
+
+After creating the Oracle Autonomous Database AI Agent, users can interact with it using prompts such as:
+
+### Discovery & Setup
+- “List all OCI regions I am subscribed to.”
+- “Show all compartments in my tenancy.”
+
+### Provisioning Autonomous Databases
+- “Help me to Provision a new Autonomous Transaction Processing database"
+
+### Listing & Inspecting Databases
+- “List all Autonomous Databases in the `Finance` compartment in the Mumbai region.”
+- “Get detailed information for the Autonomous Database with OCID `<db_ocid>`.”
+
+### Power & Lifecycle Management
+- “Start the Autonomous Database with OCID `<db_ocid>` in the Mumbai region.”
+- “Stop the Autonomous Database with OCID `<db_ocid>`.”
+- “Restart the Autonomous Database with OCID `<db_ocid>`.”
+
+### Scaling & Resource Management
+- “Increase the CPU count of the Autonomous Database `<db_ocid>` to 8 cores.”
+- “Update the storage size of the Autonomous Database `<db_ocid>` to 2 TB.”
+- “Shrink the Autonomous Database `<db_ocid>` to optimize storage usage.”
+
+### Configuration Updates
+- “Enable auto-scaling and update the display name for the Autonomous Database `<db_ocid>`.”
+- “Update backup retention to 30 days for the Autonomous Database `<db_ocid>`.”
+
+### Maintenance & Backups
+- “Show maintenance run history for maintenance run ID `<maintenance_id>`.”
+- “List all backups for the Autonomous Database `<db_ocid>` in the `Finance` compartment.”
+
+### Supporting Resources
+- “List all key stores in the `Finance` compartment.”
+- “List all DB homes in the `Finance` compartment.”
+
+
+
 ##  License
 
 Universal Permissive License (UPL) 1.0  
 https://oss.oracle.com/licenses/upl/
 
 ---
 
-## ✨ Final Thought
+## ✨ Final Thoughts
 
-This OCI Autonomous Database AI Agent turns OCI operations into a **guided, conversational, and safe experience**, blending human judgment with automation.
+This OCI Autonomous Database AI Agent turns OCI operations into a **guided, conversational**, blending human judgment with automation.
 
 It is designed for:
 - Platform teams

autonomous-ai-agents/oci_autonomous_database/oci_autonomous_database_agent.sql

@@ -10,7 +10,7 @@ rem
 rem DESCRIPTION
 rem   Installer and configuration script for OCI Autonomous Database
 rem   AI Agent using DBMS_CLOUD_AI_AGENT
-rem   (Select AI / Oracle AI Database).
+rem   (Select AI / Oracle Autonomous AI Database).
 rem
 rem   This script performs an interactive installation of an
 rem   OCI Autonomous Database AI Agent by:
@@ -231,9 +231,9 @@ BEGIN
   );
   DBMS_OUTPUT.PUT_LINE('Created team OCI_AUTONOMOUS_DATABASE_TEAM');
 
-  DBMS_OUTPUT.PUT_LINE('--------------------------------------------');
+  DBMS_OUTPUT.PUT_LINE('-------------------------------------------------');
   DBMS_OUTPUT.PUT_LINE('OCI Autonomous Database AI installation COMPLETE');
-  DBMS_OUTPUT.PUT_LINE('--------------------------------------------');
+  DBMS_OUTPUT.PUT_LINE('-------------------------------------------------');
 END install_oci_autonomous_database_agent;
 /
 

autonomous-ai-agents/oci_autonomous_database/oci_autonomous_database_tools.sql

@@ -9,11 +9,11 @@ rem   oci_autonomous_database_tools.sql
 rem
 rem DESCRIPTION
 rem   Installer script for OCI Autonomous Database AI tools
-rem   (Select AI Agent / Oracle AI Database).
+rem   (Select AI Agent / Oracle Autonomous AI Database).
 rem
 rem   This script installs a consolidated PL/SQL package and registers
 rem   AI Agent tools used to automate OCI Autonomous Database operations
-rem   via Select AI Agent (Oracle AI Database).
+rem   via Select AI Agent (Oracle Autonomous AI Database).
 rem
 rem RELEASE VERSION
 rem   1.1