Skip to content

Commit ad50295

Browse files
sandeepkhotsandeepkhot
committed
Database Inspect agent v2
1 parent d65271e commit ad50295

3 files changed

Lines changed: 1679 additions & 531 deletions

File tree

‎autonomous-ai-agents/database_inspect/README.md‎

Lines changed: 140 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,16 @@
1-
# Select AI Inspect - Database Inspection Tool Built Using Select AI Agent (26ai)
1+
# Select AI Inspect - Database Inspection Tool Built Using Select AI Agent
22

33
## Overview
44

55
Select AI Inspect is an AI-powered database inspection tool built using the **Select AI Agent** framework. It enables users to explore, understand, and interact with database objects and their metadata using natural language.
6-
This agent is supported only on Oracle Database **26ai**.
76

87
For definitions of **Tool**, **Task**, **Agent**, and **Agent Team**, see the top-level guide: [README](../README.md#simple-agent-execution-flow).
98

109
### Use Cases
1110

1211
Instead of manually reviewing tables, searching through PL/SQL files, or examining function and procedure metadata, users can simply ask the Select AI Inspect agent natural language questions such as:
1312

14-
* How are these tables related?
13+
* Which objects reference this table?
1514
* Why am I receiving this error from a function call?
1615
* What is this function used for?
1716
* What objects will be impacted if I modify this package?
@@ -36,6 +35,7 @@ Select AI Inspect supports the following database object types:
3635
* Tables
3736
* Views
3837
* Types
38+
* Type Bodies
3939
* Triggers
4040
* Functions
4141
* Procedures
@@ -49,10 +49,12 @@ Users may define the inspection scope either at the individual object level or a
4949

5050
## Prerequisites
5151

52-
- Oracle Database 26ai (Autonomous AI Database supported)
52+
- Oracle Autonomous AI Database (26ai)
5353
- Select AI and `DBMS_CLOUD_AI_AGENT` enabled
5454
- `ADMIN` or equivalent privileged user for installation
5555
- A Select AI profile created with `DBMS_CLOUD_AI.CREATE_PROFILE`
56+
- The Select AI profile used for inspection must include an `embedding_model` attribute
57+
- If the Select AI profile uses an OCI Generative AI model/provider, it must also include `oci_compartment_id`
5658

5759
---
5860

@@ -64,7 +66,7 @@ Before running installation commands:
6466
2. Open a terminal and change directory to `autonomous-ai-agents/database_inspect`.
6567
3. Choose one execution mode:
6668
- SQL*Plus/SQLcl: run script files directly with `@script_name`.
67-
- SQL Worksheet (Database Actions or other SQL IDE): open the `.sql` file and run/paste its contents.
69+
- SQL Developer or another SQL IDE: run the file in script mode so interactive prompts are shown.
6870
4. Uploading scripts to `DATA_PUMP_DIR` is not required for these methods.
6971

7072
Run as `ADMIN` (or another privileged user):
@@ -74,43 +76,134 @@ sqlplus admin@<adb_connect_string> @database_inspect_tool.sql
7476
sqlplus admin@<adb_connect_string> @database_inspect_agent.sql
7577
```
7678

77-
You can also execute the contents of `database_inspect_tool.sql` and `database_inspect_agent.sql` in SQL Worksheet.
79+
`database_inspect_agent.sql` uses interactive prompts, so run it as a script instead of copy/pasting individual statements into a worksheet.
80+
81+
### Step 1: Install `DATABASE_INSPECT` Package and Tool Framework
82+
83+
Run `database_inspect_tool.sql` first.
84+
85+
The script prompts for:
86+
87+
- `SCHEMA_NAME`: target schema where `DATABASE_INSPECT` is compiled
88+
89+
What the tools installer does:
90+
91+
- Grants required execute privileges to the target schema
92+
- Switches `CURRENT_SCHEMA` to the target schema
93+
- Compiles the `DATABASE_INSPECT` package specification and body inline
94+
- Is safe to rerun
95+
96+
Notes:
97+
98+
- The tools installer no longer executes `DATABASE_INSPECT.setup` directly from an `ADMIN` anonymous block. This avoids `ORA-06598` when the package is `AUTHID CURRENT_USER`.
99+
- Internal `DATABASE_INSPECT` tables are initialized from the target-schema execution path when the package is invoked by the agent installer or by direct package usage in the target schema.
100+
101+
### Step 2: Create or Recreate the Inspect Agent Team
102+
103+
Run `database_inspect_agent.sql` after the package is installed.
104+
105+
The script prompts for:
106+
107+
- `INSTALL_SCHEMA_NAME`: schema where the team is created
108+
- `AI_PROFILE_NAME`: profile used for reasoning and embeddings
109+
- `AGENT_TEAM_NAME`: team name to create
110+
- `RECREATE_EXISTING`: `Y` to drop and recreate an existing team, otherwise `N`
111+
- `SCOPE_MODE`: guided scope mode; supported values are `SCHEMA`, `TABLE`, `PACKAGE`, and `JSON`
112+
- `SCOPE_OWNERS`: use this for `SCHEMA` mode; enter one or more schema owners separated by commas, or leave blank to use `INSTALL_SCHEMA_NAME`
113+
- `OBJECT_OWNER`: use this for `TABLE` or `PACKAGE` mode; enter the owner/schema of the listed objects, or leave blank to use `INSTALL_SCHEMA_NAME`
114+
- `OBJECT_NAMES`: use this for `TABLE` or `PACKAGE` mode; enter one or more object names separated by commas
115+
- `MATCH_LIMIT`: optional
116+
- `TEAM_ATTRIBUTES_JSON`: use this for `JSON` mode
117+
118+
The script now shows one simple input section for these values. Enter only the fields that apply to the selected `SCOPE_MODE` and leave the others blank.
119+
120+
Guided input examples:
121+
122+
- Single schema scope:
123+
`SCOPE_MODE = SCHEMA`
124+
`SCOPE_OWNERS = <INSTALL_SCHEMA_NAME>`
125+
- Multiple schema owners:
126+
`SCOPE_MODE = SCHEMA`
127+
`SCOPE_OWNERS = SH,HR`
128+
- Multiple tables in one schema:
129+
`SCOPE_MODE = TABLE`
130+
`OBJECT_OWNER = SH`
131+
`OBJECT_NAMES = SALES,CUSTOMERS,PRODUCTS`
132+
- Multiple packages in one schema:
133+
`SCOPE_MODE = PACKAGE`
134+
`OBJECT_OWNER = HR`
135+
`OBJECT_NAMES = EMP_PKG,PAYROLL_PKG`
136+
137+
Advanced `TEAM_ATTRIBUTES_JSON` example for JSON mode:
138+
139+
```json
140+
{"object_list":[
141+
{"owner":"SH","type":"TABLE","name":"SALES"},
142+
{"owner":"SH","type":"TABLE","name":"CUSTOMERS"},
143+
{"owner":"SH","type":"TABLE","name":"PRODUCTS"}
144+
]}
145+
```
146+
147+
What the agent installer does:
148+
149+
- Grants required privileges for agent creation and background jobs, including `CREATE JOB`, `CREATE SEQUENCE`, `CREATE PROCEDURE`, and `CREATE VIEW`
150+
- Creates `DATABASE_INSPECT_AGENT_JOB_LOG$` in the target schema
151+
- Creates submitter and worker procedures in the target schema
152+
- Validates that `AI_PROFILE_NAME` has a non-null `embedding_model`
153+
- Requires `AI_PROFILE_NAME` to include `oci_compartment_id` when the profile uses an OCI Generative AI model/provider
154+
- Enforces `AI_PROFILE_NAME` as `profile_name`, even if `TEAM_ATTRIBUTES_JSON` includes a different value
155+
- Converts common installation failures into user-friendly log messages, including missing OCI compartment id, tablespace quota errors, and embedding-dimension mismatch errors
156+
- Verifies that the expected agent tools were recreated successfully
157+
158+
`RECREATE_EXISTING = Y` behavior:
159+
160+
- Cleans up any existing Select AI team, agent, and task objects for the requested team name
161+
- Drops the existing team metadata and vectorized object state
162+
- Recreates the team using the resolved attributes
163+
164+
### Monitoring Background Installation
165+
166+
Each submission writes one row to `DATABASE_INSPECT_AGENT_JOB_LOG$`.
167+
168+
Use a query like this to monitor progress:
169+
170+
```sql
171+
SELECT *
172+
FROM <INSTALL_SCHEMA_NAME>.DATABASE_INSPECT_AGENT_JOB_LOG$
173+
ORDER BY run_id DESC;
174+
```
175+
176+
Typical statuses include `PRECHECK`, `QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `TEAM_EXISTS`, and `FAILED_TO_QUEUE`.
78177

79178
---
80179

81180
## Architecture Overview
82181

83-
```text
84-
Run database_inspect_tool.sql to install DATABASE_INSPECT package and tools
85-
|
86-
v
87-
Run database_inspect_agent.sql to configure and create the inspect agent team
88-
|
89-
v
90-
Execute DATABASE_INSPECT.create_inspect_agent_team(<inspect_agent_team>, <attributes_in_json_object>)
91-
to create an inspect agent
92-
|
93-
v
182+
Run `database_inspect_tool.sql` to install the `DATABASE_INSPECT` package and prerequisites
183+
↓
184+
Run `database_inspect_agent.sql` to validate inputs and queue background installation
185+
↓
186+
`DATABASE_INSPECT_AGENT_WORKER`
187+
├── Ensures `DATABASE_INSPECT.setup` completed
188+
├── Validates profile and attributes
189+
├── Optionally drops and recreates existing team state
190+
└── Creates tools, task, team, and vectorized object metadata
191+
↓
94192
User query
95-
|
96-
v
193+
↓
97194
<inspect_agent_team>
98-
|
99-
v
100-
Agent reasoning
101-
|
102-
+-- LIST_OBJECTS
103-
+-- LIST_INCOMING_DEPENDENCIES
104-
+-- LIST_OUTGOING_DEPENDENCIES
105-
+-- RETRIEVE_OBJECT_METADATA
106-
+-- RETRIEVE_OBJECT_METADATA_CHUNKS
107-
+-- EXPAND_OBJECT_METADATA_CHUNK
108-
+-- SUMMARIZE_OBJECT
109-
`-- GENERATE_PLDOC
110-
|
111-
v
112-
Final verified answer
113-
```
195+
↓
196+
Agent Reasoning
197+
├── LIST_OBJECTS
198+
├── LIST_INCOMING_DEPENDENCIES
199+
├── LIST_OUTGOING_DEPENDENCIES
200+
├── RETRIEVE_OBJECT_METADATA
201+
├── RETRIEVE_OBJECT_METADATA_CHUNKS
202+
├── EXPAND_OBJECT_METADATA_CHUNK
203+
├── SUMMARIZE_OBJECT
204+
└── GENERATE_PLDOC
205+
↓
206+
Final Verified Answer
114207

115208
---
116209

@@ -121,12 +214,14 @@ Final verified answer
121214
├── database_inspect_tool.sql
122215
│ ├── Installer script for DATABASE_INSPECT package and tool framework
123216
│ ├── Grants required privileges to the target schema
124-
│ └── Compiles package specification and body
217+
│ ├── Compiles package specification and body
218+
│ └── Leaves internal table setup to target-schema execution
125219
│
126220
├── database_inspect_agent.sql
127221
│ ├── Installer and configuration script for DATABASE_INSPECT AI team
128-
│ ├── Accepts target schema, AI profile, and optional team attributes
129-
│ └── Recreates the inspect team using DATABASE_INSPECT package APIs
222+
│ ├── Accepts target schema, AI profile, team name, recreate flag, and optional team attributes
223+
│ ├── Logs asynchronous installation progress to DATABASE_INSPECT_AGENT_JOB_LOG$
224+
│ └── Creates or recreates the inspect team using background job execution
130225
│
131226
├── README.md
132227
└── README_nl2sql.md
@@ -199,23 +294,21 @@ DATABASE_INSPECT.update_inspect_agent_team(
199294

200295
| attribute name | description | Mandatory | attribute value format |
201296
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
202-
| profile_name | AI profile name for the agent team. If provided, the exisiting profile_name value will be overwritten. If a different AI provider is specified, the `object_list` will be re-vectorized due to embedding dimension mismatches. | N | |
297+
| profile_name | AI profile name for the agent team. If provided, the exisiting profile_name value will be overwritten. Any profile change triggers re-vectorization of the `object_list`, because embedding dimensions or similarity semantics can change even within the same provider. | N | |
203298
| object_list | List of database objects the agent team is allowed to inspect.<br />Support "owner", "type" and optional "name" for the object. if "name" is not provided, we will set all objects in the schema.<br />If provided, the original object_list will be removed and the new object_list will be vectorized. | N | e.g.<br />'[{"owner":"DEMO", "type":"schema"}]'<br />'[{"owner":"DEMO", "type":"package body", "name":"CHECKOUT_PKG"}]' |
204299
| match_limit | Specifies the maximum number of results to return in a hybrid/vector search query from RETRIEVE_OBJECT_METADATA agent tool. | N | default value is 10 |
205300

206-
207301
---
208302

209303
## Agent Setup
210304

211-
An inspection agent is created when you call `DATABASE_INSPECT.create_inspect_agent_team`.
305+
An inspection agent can be created directly by calling `DATABASE_INSPECT.create_inspect_agent_team`, but the recommended installation path is to use `database_inspect_agent.sql` so that setup, validation, logging, and background execution are handled for you.
212306

213307
### Supported Tools
214308

215309
* **list_objects**: List all available objects for the agent
216310
* **list_incoming_dependencies**: List objects that depend on or reference the given object
217311
* **list_outgoing_dependencies**: List objects that the given object itself depends on or references
218-
* **generate_graph**: Generate relationship visualizations as Mermaid graph syntax or HTML/CSS tree markup (dependency, hierarchy, binary-tree style, network)
219312
* **retrieve_object_metadata**: Retrieve the full metadata for the given object
220313
* **retrieve_object_metadata_chunks**: Retrieve a list of metadata chunks by performing hybrid search (vector search + Oracle Text search) to answer user’s query
221314
* **expand_object_metadata_chunk**: Given a selected result from the retrieve_object_metadata_chunks tool, returns an expanded metadata segment around the specified chunk to provide additional context
@@ -238,14 +331,15 @@ This schema includes more than 10 tables, such as customers, products, orders, a
238331
4. Explain what the CHECKOUT_PKG.reprice_order procedure is used for, including its purpose, parameters and business rules.
239332
5. Can you write and run a test script for the calc_tax_amount function to verify the results and check for any bugs?
240333
6. When I call the calc_tax_amount function, for state_code = 'CA' (rate 0.0825), calc_tax_amount(10.01, 'CA') returns 0.82, but it should return 0.83. Please debug the function and show me the exact code that needs to be fixed.
241-
7. Please show me a dependency graph for my table relationships.
242-
8. Show the object call hierarchy as a binary-tree style diagram.
243-
9. Render the outgoing dependency hierarchy as HTML + CSS tree markup for my web app.
334+
7. Summarize the CHECKOUT_PKG package body in one paragraph.
335+
8. Generate PLDoc comments for the calc_tax_amount function.
336+
9. Which packages and procedures will be impacted if I modify the ORDERS table?
337+
10.Get me a list of tables available for inspection.
244338

245339
---
246340

247341
## License
248342

249-
Universal Permissive License (UPL) 1.0
343+
Universal Permissive License (UPL) 1.0
250344
https://oss.oracle.com/licenses/upl/
251345
Copyright (c) 2026 Oracle and/or its affiliates.

0 commit comments

Comments
 (0)