Skip to content

Commit 8a2d989

Browse files
MarcGueuryMarcGueury
authored
Create README.md
1 parent da5bb2f commit 8a2d989

File tree

1 file changed

+187
-0
lines changed

1 file changed

+187
-0
lines changed

‎ai/gen-ai-agents/sql-tool/README.md

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
1. **Introduction**
2+
3+
- **Objective**: Step-by-step instructions for building and implementing
4+
a SQL Agent.
5+
6+
- **Overview**: SQL Agent simplifies data tasks by converting natural
7+
language queries into SQL, leveraging large language models (LLMs).
8+
Beyond language capabilities like summarization and text analysis,
9+
LLMs generate SQL, enabling users to interact with databases
10+
effortlessly, without requiring SQL expertise.
11+
12+
**2. Prerequisites**
13+
14+
- **Database Setup:**
15+
16+
> Create the database (Oracle Base Database or Autonomous Database).
17+
> Database should be in a created in a private subnet (preferred) or
18+
> protected by access control from VCN.
19+
20+
- **Create Table and Load Data**
21+
22+
> Create tables in the above database and load data. You can follow
23+
> instructions
24+
> [here](https://docs.public.content.oci.oraclecloud.com/en-us/iaas/autonomous-database-serverless/doc/load-data-autonomous.html#GUID-BCD09013-DFC9-4850-BBD2-6A90E9AE884B)
25+
> to connect to the DB and load data.
26+
27+
- **Database Tool Connection:**
28+
29+
> Create Database Tool Connection to connect to the above database.
30+
> Database Tool Connection should use a Private Endpoint to connect to
31+
> database, You can follow this
32+
> [doc](https://docs.public.content.oci.oraclecloud.com/en-us/iaas/database-tools/home.htm)
33+
> for creating a DB tool connection to any Oracle database service in
34+
> OCI.
35+
36+
- **Prepare Tool Configuration Data**
37+
38+
> User must keep the table DDLs handy before creating agent. Optionally,
39+
> they can also prepare Table Column Descriptions, In Context Examples
40+
> and Custom Instructions. These can be provided to inline to the Agent
41+
> creation wizard. Alternately, these can be uploaded Object Storage
42+
> Bucket and same be used in Agent creation wizard.
43+
44+
- **Policies**
45+
46+
- Create a dynamic group with the below matching rules.
47+
<img src="./media/image1.png"
48+
style="width:6.26806in;height:1.30556in" />
49+
50+
- Add Policies to allow above dynamic group to access resources**:**
51+
52+
allow dynamic-group \<dg-name\> to read database-tools-family in
53+
compartment \<compartment_name\>
54+
allow dynamic-group \<dg-name\> to use database-tools-connections in
55+
compartment \<compartment_name\>
56+
allow dynamic-group \<dg-name\> to read secret-family in compartment
57+
\<compartment_name\>
58+
allow dynamic-group \<dg-name\> to read objects in tenancy
59+
60+
**3. Setting Up the OCI Environment**
61+
62+
**3.1 Logging into OCI Console**
63+
64+
1. Navigate to the [OCI Console](https://www.oracle.com/cloud/).
65+
66+
2. <img src="./media/image2.png"
67+
style="width:6.34306in;height:3.30694in" />Enter your credentials
68+
and click **Sign In** and open Generative AI Agents service.
69+
70+
**4. Creating an agent**
71+
72+
1. Click on **Agent** and select the appropriate **Compartment** where
73+
you want to create the agent.
74+
75+
2. Click on the **Create Agent** button and complete the required
76+
fields:
77+
78+
1. Basic Information
79+
80+
1. Enter the mandatory fields: **Name** and **Welcome
81+
Message**. The **Description** field is optional.
82+
83+
2. Check the box to create endpoints for the agent.
84+
85+
3. <img src="./media/image3.png"
86+
style="width:6.94583in;height:3.29028in" />You can also
87+
allow to add tags to organise this resource. For more info
88+
check
89+
[this](https://docs.oracle.com/en-us/iaas/Content/Tagging/Concepts/taggingoverview.htm).
90+
Refer below screenshot.
91+
92+
2. **Knowledge bases – Not required for SQL.**
93+
94+
3. **Tools**: Select Conserve with your structured data in
95+
database(SQL). Fill in the configuration as described below.
96+
97+
1. **Name**: You need to give a meaningful name to your agent.
98+
99+
2. **Description**: Provide a detailed summary of the data to
100+
be used or query via this tool.
101+
102+
3. **Database schema**: There are two options available to
103+
import the database schema configuration for this tool.
104+
105+
- **Inline** –you can directly paste the SQL schema in the
106+
text box.
107+
<img src="./media/image4.png" style="width:6.5in;height:3.79375in" />
108+
109+
- **Choose from object storage** – You can also import the
110+
database schema configuration from an object storage
111+
bucket. Ensure you have the correct access permissions for
112+
this.
113+
<img src="./media/image5.png" style="width:6.55947in;height:3.06in" />
114+
115+
4. **Model customization** : It has two option. Choose based on
116+
your preference.
117+
118+
- Small(cost-effective) – takes less time to create but less
119+
accuracy.
120+
121+
- Large(more accurate) – longer time but better accuracy.
122+
123+
5. **Dialect** : slightly different variations of SQL, called
124+
dialects. While the core SQL syntax is consistent. we
125+
provide two option for this as well.
126+
127+
- SQLite
128+
129+
- Oracle SQL
130+
<img src="./media/image6.png" style="width:6.21798in;height:2.8782in" />
131+
132+
6. **In-Context Learning Examples:** Provide examples to help
133+
the tool generate more accurate queries. This step is
134+
optional. You can import examples either inline or from an
135+
object storage bucket. <img src="./media/image7.png"
136+
style="width:6.89744in;height:1.08578in" />**
137+
**
138+
139+
7. **Database tool connection:** you need to select and test
140+
appropriate connection tool present in your compartment.
141+
<img src="./media/image8.png"
142+
style="width:6.73316in;height:3.89387in" />
143+
144+
8. **Enable SQL Execution**: To enable SQL execution, turn on
145+
the **Enable SQL Execution** button. This allows the SQL
146+
Agent to execute the query and return the result. If
147+
disabled, the agent will not be able to execute the query.
148+
149+
9. **Enable Self-Correction**: Enable **Self-Correction** by
150+
turning on the **Enable Self-Correction** button. This
151+
allows the SQL Agent to automatically correct the query if
152+
any corrections are needed.
153+
<img src="./media/image9.png"
154+
style="width:4.37304in;height:2.68482in" />
155+
156+
10. **Custom instructions** : you can give custom instructions
157+
like below examples. Or can leave it empty.
158+
<img src="./media/image10.png"
159+
style="width:6.52429in;height:0.98215in" />
160+
161+
11. D**escription of tables and columns:** You can use this
162+
option to provide descriptions for tables and columns.
163+
Descriptions can be imported from object storage, added
164+
inline, or left blank (none).
165+
<img src="./media/image11.png" style="width:6.5in;height:2.02917in" />
166+
167+
3. <img src="./media/image12.png"
168+
style="width:6.91319in;height:3.10278in" />Click on next button,
169+
review and create an agent.
170+
171+
**4. Launch chat**
172+
173+
1. Once the agent is ready and tool is created. You can launch the
174+
chat.
175+
<img src="./media/image13.png" style="width:6.26806in;height:3.1in" />
176+
177+
2. This is how the chat interface will appear, displaying the same
178+
**Welcome Message** that you provided earlier.
179+
<img src="./media/image14.png"
180+
style="width:6.1604in;height:2.68086in" />
181+
182+
2. You can start asking some basic question to get SQL query like
183+
this.
184+
<img src="./media/image15.png"
185+
style="width:6.26806in;height:2.51389in" />
186+
187+
3. You can reset chat session to start new chat.

0 commit comments

Comments
 (0)