Skip to content

Commit d18b9b9

Browse files
gopalsanjithgopalsanjith
committed
header updates
1 parent ed020b6 commit d18b9b9

File tree

11 files changed

+992
-886
lines changed

11 files changed

+992
-886
lines changed

‎autonomous-ai-agents/README.md‎

Lines changed: 281 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,300 @@
1-
# Autonomous AI Agents — Quick Install Guide (OCI Object Storage + OCI Vault)
1+
# Autonomous AI Agents for OCI (Oracle Autonomous Database)
22

3-
This guide shows how to install and use the two SQL installer scripts:
4-
- oci_object_storage_agent_install.sql
5-
- oci_vault_agent_install.sql
3+
## Overview
64

7-
What gets installed
8-
- A config table in your target schema: OCI_AGENT_CONFIG
9-
- A PL/SQL package with ready-to-use functions
10-
- AI Agent tools (DBMS_CLOUD_AI_AGENT) mapped to those functions
5+
This repository provides a **modular, extensible framework** for building **OCI AI Agents** using **Oracle Autonomous Database** and **`DBMS_CLOUD_AI_AGENT` (Select AI)**.
116

12-
Important
13-
- INSTALL_SCHEMA is mandatory. Always set it.
7+
Each OCI service (Vault, Object Storage, Autonomous Database, Network Load Balancer, etc.) is implemented using a **two-layer model**:
148

15-
Prerequisites
16-
- A DBMS_CLOUD credential with OCI permissions for the target compartment(s)
17-
- The target schema name (INSTALL_SCHEMA) where packages/tools/config will live
9+
- **Tools Layer**
10+
- Installs reusable PL/SQL functions
11+
- Registers them as AI tools
12+
- **Agent Layer**
13+
- Creates sample tasks, agents, and teams
14+
- Consumes the tools created in the Tools layer
1815

19-
1) Create or identify a DBMS_CLOUD credential
20-
Example (if needed):
21-
```
22-
BEGIN
23-
DBMS_CLOUD.CREATE_CREDENTIAL(
24-
credential_name => 'MY_CRED',
25-
username => '<oci_user_or_principal>',
26-
password => '<oci_auth_token_or_secret>'
27-
);
28-
END;
29-
/
30-
```
16+
### Benefits of This Design
3117

32-
2) Install — set variables and run the scripts
33-
Use SQL*Plus q'(...)' quoting for JSON so you don't need to escape quotes.
18+
- Reuse tools across multiple agents
19+
- Allow end users to create custom agents and tasks
20+
- Clear separation of:
21+
- Infrastructure logic
22+
- AI orchestration logic
3423

35-
Connect:
36-
```
37-
sqlplus admin@<tns_alias>
38-
```
24+
---
3925

40-
Set variables (mandatory INSTALL_SCHEMA, optional INSTALL_CONFIG_JSON):
41-
```
42-
DEFINE INSTALL_SCHEMA = 'YOUR_APP_SCHEMA';
43-
DEFINE INSTALL_CONFIG_JSON = q'({"credential_name": "MY_CRED", "compartment_name": "MY_COMP"})';
44-
```
26+
## Design Principles
4527

46-
Run one or both installers:
47-
```
48-
@autonomous_ai_agents/oci_object_storage_agent_install.sql
49-
@autonomous_ai_agents/oci_vault_agent_install.sql
50-
```
28+
### 1. Two-Layer Architecture
29+
30+
Each OCI service is implemented using **two SQL scripts**:
31+
32+
| Layer | Script Pattern | Purpose |
33+
|------|---------------|---------|
34+
| Tools Layer | `*_tools.sql` | Installs core PL/SQL logic and registers AI tools |
35+
| Agent Layer | `*_agent.sql` | Creates a sample Task, Agent, and Team using those tools |
36+
37+
This design ensures:
38+
- Tools are reusable across multiple agents
39+
- Agent behavior remains customizable
40+
41+
---
5142

52-
Notes
53-
- INSTALL_CONFIG_JSON is optional (defaults to NULL).
54-
- Recommended keys to include if you pass JSON:
55-
- credential_name: your DBMS_CLOUD credential name
56-
- compartment_name: name of the compartment
43+
## Tools Scripts (`*_tools.sql`)
5744

58-
3) If you didn’t pass INSTALL_CONFIG_JSON, you can still configure the
59-
agent after installation by adding rows to YOUR_APP_SCHEMA.OCI_AGENT_CONFIG.
60-
Each agent has its own AGENT value
61-
- For object storage use OCI_OBJECT_STORAGE
62-
- For vault use OCI_VAULT
45+
### Purpose
6346

64-
Examples (Object Storage)
47+
Tools scripts are responsible for **infrastructure and capability enablement**.
6548

66-
Set credential name for Object Storage operations:
49+
**Example:**
50+
- `oci_vault_tools.sql`
51+
52+
---
53+
54+
### What a Tools Script Does
55+
56+
A tools script typically performs the following steps:
57+
58+
#### 1. Grant Required Privileges
59+
60+
- Grants access to:
61+
- `DBMS_CLOUD`
62+
- `DBMS_CLOUD_AI`
63+
- `DBMS_CLOUD_AI_AGENT`
64+
- Relevant OCI typed API packages
65+
- Privileges are scoped to the **target schema**
66+
67+
---
68+
69+
#### 2. Create Configuration Table
70+
71+
Creates a generic configuration table:
72+
73+
```sql
74+
OCI_AGENT_CONFIG
6775
```
68-
INSERT INTO YOUR_APP_SCHEMA.OCI_AGENT_CONFIG ("KEY","VALUE","AGENT")
69-
VALUES ('CREDENTIAL_NAME', 'MY_CRED', 'OCI_OBJECT_STORAGE');
76+
77+
**Stores configuration such as:**
78+
- Credential name
79+
- Compartment name / OCID
80+
- Resource principal enablement
81+
82+
> Configuration is **agent-specific** and persisted for runtime use.
83+
84+
---
85+
86+
#### 3. Initialize Configuration
87+
88+
- Parses optional JSON configuration input
89+
- Enables resource principal authentication if requested
90+
- Persists configuration values
91+
92+
---
93+
94+
#### 4. Create PL/SQL Package
95+
96+
**Example package:**
97+
98+
```sql
99+
oci_vault_agents
70100
```
71101

72-
Set compartment name for Vault
102+
**Package responsibilities:**
103+
- Implements core OCI API logic
104+
- Calls OCI APIs using `DBMS_CLOUD_OCI_*`
105+
- Each function:
106+
- Returns **CLOB JSON**
107+
- Includes:
108+
- Status codes
109+
- Headers
110+
- Response payloads
111+
112+
---
113+
114+
#### 5. Register AI Tools
115+
116+
- Uses `DBMS_CLOUD_AI_AGENT.CREATE_TOOL`
117+
- Maps each PL/SQL function to an AI tool
118+
- Adds rich instructions describing:
119+
- When to use the tool
120+
- Safety rules (e.g. no secret exposure)
121+
- Expected behavior
122+
123+
---
124+
125+
### Key Characteristics of Tools
126+
127+
- Service-specific but **agent-agnostic**
128+
- Reusable by any task or agent
129+
- Safe to re-run (drop & recreate logic)
130+
- Designed for **human-readable AI responses**
131+
132+
---
133+
134+
## Agent Scripts (`*_agent.sql`)
135+
136+
### Purpose
137+
138+
Agent scripts create **example AI agents** demonstrating how to use the tools.
139+
140+
**Example:**
141+
- `oci_vault_agent.sql`
142+
143+
---
144+
145+
### What an Agent Script Does
146+
147+
#### 1. Interactive Execution
148+
149+
Prompts for:
150+
- Target schema name
151+
- AI Profile name
152+
153+
This makes scripts **portable across environments**.
154+
155+
---
156+
157+
#### 2. Grant Required Privileges
158+
159+
Grants:
160+
- `DBMS_CLOUD_AI_AGENT`
161+
- `DBMS_CLOUD`
162+
163+
To the target schema.
164+
165+
---
166+
167+
#### 3. Create Installer Procedure
168+
169+
- Creates an installer procedure in the target schema
170+
- Keeps all agent logic **schema-local**
171+
172+
---
173+
174+
#### 4. Create AI Task
175+
176+
Defines:
177+
- User intent detection
178+
- Allowed tools
179+
- Safety rules
180+
- Formatting expectations
181+
182+
Enforces:
183+
- Confirmation for destructive actions
184+
- Human-readable output
185+
186+
---
187+
188+
#### 5. Create AI Agent
189+
190+
- Binds the agent to the specified AI Profile
191+
- Defines the agent’s role and behavior
192+
193+
---
194+
195+
#### 6. Create AI Team
196+
197+
- Links the agent and task
198+
- Uses **sequential execution**
199+
200+
---
201+
202+
#### 7. Execute Installer
203+
204+
- Runs the installer procedure
205+
- Completes agent setup
206+
207+
---
208+
209+
### Key Characteristics of Agents
210+
211+
- Agents are **examples**, not hard dependencies
212+
- End users can:
213+
- Modify tasks
214+
- Create new agents
215+
- Create multiple teams
216+
- Tools remain unchanged and reusable
217+
218+
---
219+
220+
## Example: OCI Vault
221+
222+
### Files
223+
224+
| File | Description |
225+
|-----|------------|
226+
| `oci_vault_tools.sql` | Installs Vault PL/SQL package, config table, and AI tools |
227+
| `oci_vault_agent.sql` | Creates a sample Vault task, agent, and team |
228+
229+
---
230+
231+
### Supported Capabilities
232+
233+
The Vault tools support:
234+
235+
- List secrets
236+
- Get secret metadata
237+
- Create secrets
238+
- Update secrets / rotate versions
239+
- List secret versions
240+
- Get specific secret versions
241+
- Schedule and cancel deletions
242+
- Change secret compartment
243+
244+
**All operations:**
245+
- Use persisted configuration
246+
- Require confirmation for destructive actions
247+
- Never expose secret payloads unintentionally
248+
249+
---
250+
251+
## Installation Order (Recommended)
252+
253+
For each OCI service:
254+
255+
1. Run `*_tools.sql`
256+
2. Run `*_agent.sql` (optional, for sample agent)
257+
258+
### Example (OCI Vault)
259+
260+
```sql
261+
-- Step 1: Install tools
262+
sqlplus admin@db @oci_vault_tools.sql <INSTALL_SCHEMA>
263+
264+
-- Step 2: Install sample agent
265+
sqlplus admin@db @oci_vault_agent.sql
73266
```
74-
INSERT INTO YOUR_APP_SCHEMA.OCI_AGENT_CONFIG ("KEY","VALUE","AGENT")
75-
VALUES ('COMPARTMENT_NAME', 'MY_COMP', 'OCI_VAULT');
267+
268+
---
269+
270+
## Customization & Extension
271+
272+
- Create your own tasks, agents, and teams
273+
- Tools remain stable and reusable
274+
- Multiple agents can share the same tools
275+
- Configuration can be updated in:
276+
277+
```sql
278+
OCI_AGENT_CONFIG
76279
```
77280

281+
---
282+
283+
## Error Handling & Safety
284+
285+
- Scripts exit immediately on SQL errors
286+
- All destructive OCI operations require confirmation
287+
- Tools return structured JSON containing:
288+
- Status
289+
- Headers
290+
- Payload
291+
- Fully re-runnable with safe drop-and-create logic
292+
293+
---
294+
295+
## License
296+
297+
This project is licensed under the **Universal Permissive License (UPL), Version 1.0**.
298+
299+
See:
300+
https://oss.oracle.com/licenses/upl/

0 commit comments

Comments
 (0)