agents creation templates

autonomous-ai-agents/README.md

@@ -1,77 +1,300 @@
-# Autonomous AI Agents — Quick Install Guide (OCI Object Storage + OCI Vault)
+# Autonomous AI Agents for OCI (Oracle Autonomous Database)
 
-This guide shows how to install and use the two SQL installer scripts:
-- oci_object_storage_agent_install.sql
-- oci_vault_agent_install.sql
+## Overview
 
-What gets installed
-- A config table in your target schema: OCI_AGENT_CONFIG
-- A PL/SQL package with ready-to-use functions
-- AI Agent tools (DBMS_CLOUD_AI_AGENT) mapped to those functions
+This repository provides a **modular, extensible framework** for building **OCI AI Agents** using **Oracle Autonomous Database** and **`DBMS_CLOUD_AI_AGENT` (Select AI)**.
 
-Important
-- INSTALL_SCHEMA is mandatory. Always set it.
+Each OCI service (Vault, Object Storage, Autonomous Database, Network Load Balancer, etc.) is implemented using a **two-layer model**:
 
-Prerequisites
-- A DBMS_CLOUD credential with OCI permissions for the target compartment(s)
-- The target schema name (INSTALL_SCHEMA) where packages/tools/config will live
+- **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
 
-1) Create or identify a DBMS_CLOUD credential
-Example (if needed):
-```
-BEGIN
-  DBMS_CLOUD.CREATE_CREDENTIAL(
-    credential_name => 'MY_CRED',
-    username        => '<oci_user_or_principal>',
-    password        => '<oci_auth_token_or_secret>'
-  );
-END;
-/
-```
+### Benefits of This Design
 
-2) Install — set variables and run the scripts
-Use SQL*Plus q'(...)' quoting for JSON so you don't need to escape quotes.
+- Reuse tools across multiple agents
+- Allow end users to create custom agents and tasks
+- Clear separation of:
+  - Infrastructure logic
+  - AI orchestration logic
 
-Connect:
-```
-sqlplus admin@<tns_alias>
-```
+---
 
-Set variables (mandatory INSTALL_SCHEMA, optional INSTALL_CONFIG_JSON):
-```
-DEFINE INSTALL_SCHEMA = 'YOUR_APP_SCHEMA';
-DEFINE INSTALL_CONFIG_JSON = q'({"credential_name": "MY_CRED", "compartment_name": "MY_COMP"})';
-```
+## Design Principles
 
-Run one or both installers:
-```
-@autonomous_ai_agents/oci_object_storage_agent_install.sql
-@autonomous_ai_agents/oci_vault_agent_install.sql
-```
+### 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
+
+---
 
-Notes
-- INSTALL_CONFIG_JSON is optional (defaults to NULL).
-- Recommended keys to include if you pass JSON:
-  - credential_name: your DBMS_CLOUD credential name
-  - compartment_name: name of the compartment
+## Tools Scripts (`*_tools.sql`)
 
-3) If you didn’t pass INSTALL_CONFIG_JSON, you can still configure the 
-agent after installation by adding rows to YOUR_APP_SCHEMA.OCI_AGENT_CONFIG.
-Each agent has its own AGENT value
-- For object storage use OCI_OBJECT_STORAGE
-- For vault use OCI_VAULT
+### Purpose
 
-Examples (Object Storage)
+Tools scripts are responsible for **infrastructure and capability enablement**.
 
-Set credential name for Object Storage operations:
+**Example:**
+- `oci_vault_tools.sql`
+
+---
+
+### What a Tools Script Does
+
+A tools script typically performs the following steps:
+
+#### 1. Grant Required Privileges
+
+- Grants access to:
+  - `DBMS_CLOUD`
+  - `DBMS_CLOUD_AI`
+  - `DBMS_CLOUD_AI_AGENT`
+  - Relevant OCI typed API packages
+- Privileges are scoped to the **target schema**
+
+---
+
+#### 2. Create Configuration Table
+
+Creates a generic configuration table:
+
+```sql
+OCI_AGENT_CONFIG
 ```
-INSERT INTO YOUR_APP_SCHEMA.OCI_AGENT_CONFIG ("KEY","VALUE","AGENT")
-VALUES ('CREDENTIAL_NAME', 'MY_CRED', 'OCI_OBJECT_STORAGE');
+
+**Stores configuration such as:**
+- Credential name
+- Compartment name / OCID
+- Resource principal enablement
+
+> Configuration is **agent-specific** and persisted for runtime use.
+
+---
+
+#### 3. Initialize Configuration
+
+- Parses optional JSON configuration input
+- Enables resource principal authentication if requested
+- Persists configuration values
+
+---
+
+#### 4. Create PL/SQL Package
+
+**Example package:**
+
+```sql
+oci_vault_agents
 ```
 
-Set compartment name for Vault
+**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
+
+---
+
+#### 5. Register AI Tools
+
+- 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
+
+---
+
+### Key Characteristics of Tools
+
+- Service-specific but **agent-agnostic**
+- Reusable by any task or agent
+- Safe to re-run (drop & recreate logic)
+- Designed for **human-readable AI responses**
+
+---
+
+## Agent Scripts (`*_agent.sql`)
+
+### Purpose
+
+Agent scripts create **example AI agents** demonstrating how to use the tools.
+
+**Example:**
+- `oci_vault_agent.sql`
+
+---
+
+### What an Agent Script Does
+
+#### 1. Interactive Execution
+
+Prompts for:
+- Target schema name
+- AI Profile name
+
+This makes scripts **portable across environments**.
+
+---
+
+#### 2. Grant Required Privileges
+
+Grants:
+- `DBMS_CLOUD_AI_AGENT`
+- `DBMS_CLOUD`
+
+To the target schema.
+
+---
+
+#### 3. Create Installer Procedure
+
+- Creates an installer procedure in the target schema
+- Keeps all agent logic **schema-local**
+
+---
+
+#### 4. Create AI Task
+
+Defines:
+- User intent detection
+- Allowed tools
+- Safety rules
+- Formatting expectations
+
+Enforces:
+- Confirmation for destructive actions
+- Human-readable output
+
+---
+
+#### 5. Create AI Agent
+
+- Binds the agent to the specified AI Profile
+- Defines the agent’s role and behavior
+
+---
+
+#### 6. Create AI Team
+
+- Links the agent and task
+- Uses **sequential execution**
+
+---
+
+#### 7. Execute Installer
+
+- Runs the installer procedure
+- Completes agent setup
+
+---
+
+### Key Characteristics of Agents
+
+- Agents are **examples**, not hard dependencies
+- End users can:
+  - Modify tasks
+  - Create new agents
+  - Create multiple teams
+- Tools remain unchanged and reusable
+
+---
+
+## 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 |
+
+---
+
+### Supported Capabilities
+
+The Vault tools support:
+
+- 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
+
+---
+
+## Installation Order (Recommended)
+
+For each OCI service:
+
+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
 ```
-INSERT INTO YOUR_APP_SCHEMA.OCI_AGENT_CONFIG ("KEY","VALUE","AGENT")
-VALUES ('COMPARTMENT_NAME', 'MY_COMP', 'OCI_VAULT');
+
+---
+
+## Customization & Extension
+
+- Create your own tasks, agents, and teams
+- Tools remain stable and reusable
+- Multiple agents can share the same tools
+- Configuration can be updated in:
+
+```sql
+OCI_AGENT_CONFIG
 ```
 
+---
+
+## 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
+
+---
+
+## License
+
+This project is licensed under the **Universal Permissive License (UPL), Version 1.0**.
+
+See:
+https://oss.oracle.com/licenses/upl/