Merge pull request #59 from sandeepkhot/Select_AI_Agents_v1

NL2SQL Data Retrieval Agent

Author: jpmc-github

autonomous-ai-agents/README.md

@@ -1,300 +1,176 @@
-# Autonomous AI Agents for OCI (Oracle Autonomous Database)
 
-## Overview
-
-This repository provides a **modular, extensible framework** for building **OCI AI Agents** using **Oracle Autonomous Database** and **`DBMS_CLOUD_AI_AGENT` (Select AI)**.
-
-Each OCI service (Vault, Object Storage, Autonomous Database, Network Load Balancer, etc.) is implemented using a **two-layer model**:
-
-- **Tools Layer**
-  - Installs reusable PL/SQL functions
-  - Registers them as AI tools
-- **Agent Layer**
-  - Creates sample tasks, agents, and teams
-  - Consumes the tools created in the Tools layer
-
-### Benefits of This Design
-
-- Reuse tools across multiple agents
-- Allow end users to create custom agents and tasks
-- Clear separation of:
-  - Infrastructure logic
-  - AI orchestration logic
-
----
-
-## Design Principles
-
-### 1. Two-Layer Architecture
-
-Each OCI service is implemented using **two SQL scripts**:
-
-| Layer | Script Pattern | Purpose |
-|------|---------------|---------|
-| Tools Layer | `*_tools.sql` | Installs core PL/SQL logic and registers AI tools |
-| Agent Layer | `*_agent.sql` | Creates a sample Task, Agent, and Team using those tools |
-
-This design ensures:
-- Tools are reusable across multiple agents
-- Agent behavior remains customizable
-
----
-
-## Tools Scripts (`*_tools.sql`)
-
-### Purpose
-
-Tools scripts are responsible for **infrastructure and capability enablement**.
+# Select AI Agents on Oracle Autonomous AI Database
 
-**Example:**
-- `oci_vault_tools.sql`
-
----
-
-### What a Tools Script Does
+## Overview
 
-A tools script typically performs the following steps:
+This repository provides a **generic, extensible framework for building Select AI Agents on Oracle Autonomous AI Database** using the **Select AI Agent framework**.
 
-#### 1. Grant Required Privileges
+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.
 
-- Grants access to:
-  - `DBMS_CLOUD`
-  - `DBMS_CLOUD_AI`
-  - `DBMS_CLOUD_AI_AGENT`
-  - Relevant OCI typed API packages
-- Privileges are scoped to the **target schema**
+The agents in this repository are **generic Select AI agents**. While some examples may interact with Oracle services, the framework itself is not limited to any specific domain or platform and can support many different types of agents and workflows.
 
 ---
 
-#### 2. Create Configuration Table
+## What is a Select AI Agent?
 
-Creates a generic configuration table:
+Select AI Agents are part of the Oracle Autonomous AI Database Select AI framework. A Select AI Agent:
 
-```sql
-OCI_AGENT_CONFIG
-```
-
-**Stores configuration such as:**
-- Credential name
-- Compartment name / OCID
-- Resource principal enablement
-
-> Configuration is **agent-specific** and persisted for runtime use.
+- 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 responses
 
----
+Key characteristics of the Select AI Agent framework include:
 
-#### 3. Initialize Configuration
+- Native integration with Oracle Autonomous AI Database
+- Tool execution through PL/SQL
+- Support for tasks, agents, and teams
+- Centralized governance and monitoring
+- Flexibility to build domain-specific or generic agents
 
-- Parses optional JSON configuration input
-- Enables resource principal authentication if requested
-- Persists configuration values
+For full details, refer to the official documentation:
+https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-agent.html
 
 ---
 
-#### 4. Create PL/SQL Package
-
-**Example package:**
-
-```sql
-oci_vault_agents
-```
-
-**Package responsibilities:**
-- Implements core OCI API logic
-- Calls OCI APIs using `DBMS_CLOUD_OCI_*`
-- Each function:
-  - Returns **CLOB JSON**
-  - Includes:
-    - Status codes
-    - Headers
-    - Response payloads
+## Design Principles
 
----
+### 1. Two-Layer Architecture
 
-#### 5. Register AI Tools
+Each agent implementation follows a two-layer model using separate SQL scripts.
 
-- Uses `DBMS_CLOUD_AI_AGENT.CREATE_TOOL`
-- Maps each PL/SQL function to an AI tool
-- Adds rich instructions describing:
-  - When to use the tool
-  - Safety rules (e.g. no secret exposure)
-  - Expected behavior
+| Layer        | Script Pattern   | Purpose |
+|--------------|-----------------|---------|
+| Tools Layer  | `*_tools.sql`   | Installs core PL/SQL logic and registers Select AI tools |
+| Agent Layer  | `*_agent.sql`   | Creates a sample Task, Agent, and Team using those tools |
 
----
+This design provides:
 
-### Key Characteristics of Tools
+- **Tools** that are reusable across multiple agents  
+- **Agents** as examples for customizable behavior
 
-- Service-specific but **agent-agnostic**
-- Reusable by any task or agent
-- Safe to re-run (drop & recreate logic)
-- Designed for **human-readable AI responses**
+The clear separation between tools and agents allows infrastructure logic to remain stable while agent behavior can be easily adapted or extended.
 
 ---
 
-## Agent Scripts (`*_agent.sql`)
+## Repository Structure
 
-### Purpose
+The repository is organized to align with the Select AI Agent framework:
 
-Agent scripts create **example AI agents** demonstrating how to use the tools.
-
-**Example:**
-- `oci_vault_agent.sql`
+- Tools scripts define and register reusable PL/SQL functions
+- Agent scripts demonstrate how those tools are composed into tasks, agents, and teams
+- Additional agents can be created without modifying existing tools
 
 ---
 
-### What an Agent Script Does
+## Agent Configuration (`SELECTAI_AGENT_CONFIG`)
 
-#### 1. Interactive Execution
+### Overview
 
-Prompts for:
-- Target schema name
-- AI Profile name
+Select AI agents use a shared configuration table named `SELECTAI_AGENT_CONFIG` to store **agent-specific configuration parameters**.
 
-This makes scripts **portable across environments**.
+The table is generic and can be used by any Select AI agent (for example, NL2SQL data retrieval agents or other domain-specific agents). Each agent persists only the configuration keys it requires, while default behavior applies when values are not provided.
 
 ---
 
-#### 2. Grant Required Privileges
+### Column Description
 
-Grants:
-- `DBMS_CLOUD_AI_AGENT`
-- `DBMS_CLOUD`
+| Column | Description |
+|------|------------|
+| `ID` | System-generated unique identifier |
+| `KEY` | Configuration parameter name |
+| `VALUE` | Configuration value (stored as CLOB) |
+| `AGENT` | Logical name of the Select AI agent(Available in tools) |
 
-To the target schema.
+Configuration entries are uniquely identified by the combination of `KEY` and `AGENT`.
 
 ---
 
-#### 3. Create Installer Procedure
+### Writing Configuration Entries
 
-- Creates an installer procedure in the target schema
-- Keeps all agent logic **schema-local**
+Configuration values are written during agent installation or setup.  
+Only explicitly provided values are persisted; agents apply internal defaults when values are absent.
 
 ---
 
-#### 4. Create AI Task
-
-Defines:
-- User intent detection
-- Allowed tools
-- Safety rules
-- Formatting expectations
+### Example Configuration Entries
 
-Enforces:
-- Confirmation for destructive actions
-- Human-readable output
+#### NL2SQL Data Retrieval Agent
 
----
+```sql
+INSERT INTO SELECTAI_AGENT_CONFIG ("KEY", "VALUE", "AGENT")
+VALUES ('ENABLE_RESOURCE_PRINCIPAL', 'YES', 'NL2SQL_DATA_RETRIEVAL_AGENT');
 
-#### 5. Create AI Agent
+INSERT INTO SELECTAI_AGENT_CONFIG ("KEY", "VALUE", "AGENT")
+VALUES ('CREDENTIAL_NAME', 'MY_DB_CREDENTIAL', 'NL2SQL_DATA_RETRIEVAL_AGENT');
+```
 
-- Binds the agent to the specified AI Profile
-- Defines the agent’s role and behavior
+### JSON-Based Configuration Input
 
----
+Agent installers may accept configuration as JSON input.
 
-#### 6. Create AI Team
+Example:
 
-- Links the agent and task
-- Uses **sequential execution**
+```{
+  "use_resource_principal": true,
+  "credential_name": "MY_DB_CREDENTIAL"
+}
+```
 
----
+The installer parses the JSON and stores the relevant values in SELECTAI_AGENT_CONFIG.
 
-#### 7. Execute Installer
+### Reading Configuration at Runtime
 
-- Runs the installer procedure
-- Completes agent setup
+At runtime, agents read their configuration from SELECTAI_AGENT_CONFIG and consume it as structured JSON. This allows configuration changes without modifying agent code.
 
----
 
-### Key Characteristics of Agents
+## Supported Use Cases
 
-- Agents are **examples**, not hard dependencies
-- End users can:
-  - Modify tasks
-  - Create new agents
-  - Create multiple teams
-- Tools remain unchanged and reusable
+This framework can be used to build Select AI agents for:
 
----
+- Natural language to SQL (NL2SQL)
+- Data retrieval and analytics
+- Database administration and monitoring
+- Operational workflows
+- Custom enterprise automation
 
-## Example: OCI Vault
-
-### Files
-
-| File | Description |
-|-----|------------|
-| `oci_vault_tools.sql` | Installs Vault PL/SQL package, config table, and AI tools |
-| `oci_vault_agent.sql` | Creates a sample Vault task, agent, and team |
+Agents can target database-only workflows, service integrations, or mixed enterprise use cases.
 
 ---
 
-### Supported Capabilities
+## Compatibility and Release Support
 
-The Vault tools support:
+Select AI capabilities vary by database release. For details on supported features across Autonomous Database and compatible non-Autonomous Database releases, refer to the official Select AI Capability Matrix:
 
-- List secrets
-- Get secret metadata
-- Create secrets
-- Update secrets / rotate versions
-- List secret versions
-- Get specific secret versions
-- Schedule and cancel deletions
-- Change secret compartment
-
-**All operations:**
-- Use persisted configuration
-- Require confirmation for destructive actions
-- Never expose secret payloads unintentionally
+https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/select-ai-capability-matrix.pdf
 
 ---
 
-## Installation Order (Recommended)
-
-For each OCI service:
+## Getting Started
 
-1. Run `*_tools.sql`
-2. Run `*_agent.sql` (optional, for sample agent)
-
-### Example (OCI Vault)
-
-```sql
--- Step 1: Install tools
-sqlplus admin@db @oci_vault_tools.sql <INSTALL_SCHEMA>
-
--- Step 2: Install sample agent
-sqlplus admin@db @oci_vault_agent.sql
-```
+1. Run the Tools layer scripts to install and register Select AI tools.
+2. Run the Agent layer scripts to create sample tasks, agents, and teams.
+3. Customize existing agents or create new ones by composing available tools.
+4. Extend the framework by adding new tools and agent definitions.
 
 ---
 
-## Customization & Extension
+## Intended Audience
 
-- Create your own tasks, agents, and teams
-- Tools remain stable and reusable
-- Multiple agents can share the same tools
-- Configuration can be updated in:
+This repository is intended for:
 
-```sql
-OCI_AGENT_CONFIG
-```
+- Database developers
+- Data engineers
+- Architects
+- Platform teams
+- AI practitioners working with Oracle Autonomous AI Database
 
----
-
-## Error Handling & Safety
-
-- Scripts exit immediately on SQL errors
-- All destructive OCI operations require confirmation
-- Tools return structured JSON containing:
-  - Status
-  - Headers
-  - Payload
-- Fully re-runnable with safe drop-and-create logic
+Anyone looking to build secure, database-native AI agents using Select AI can use this repository as a starting point.
 
 ---
 
 ## License
 
 This project is licensed under the **Universal Permissive License (UPL), Version 1.0**.
-
-See:
-https://oss.oracle.com/licenses/upl/
+See: https://oss.oracle.com/licenses/upl/