Oracle Cloud Infrastructure Documentation

Creating a SQL Tool in Generative AI Agents

In Generative AI Agents, each agent must have one or more tools. You can create an agent's tool during or after creating the agent. For both options, creating a tool has the same steps. This section shows you the steps to create a SQL tool.

Before you create a SQL tool, review the SQL Tool Guidelines for Generative AI Agents and complete any tasks that are required.

Creating a SQL Tool

  1. Select Create tool and then select SQL.
  2. Enter a name and a description for this SQL tool.
    A description of the database schema in this tool helps the agent better understand how to generate SQL query statements.
  3. For Import database schema configuration, select one of the following options to provide the database schema to use for this tool. A schema is a set of SQL statements that must include tables, columns, data types, and relationships to define the organization of objects in the database.
    • Inline: Enter a string that contains the SQL statements. The string must start with a valid SQL keyword such as CREATE and ALTER, or an opening parenthesis (.
    • Choose from Object Storage: Select a compartment and a bucket. Then select the .sql file that contains the SQL statements.
  4. For Model customization, select one of the following options.
    • Small: Select for simple queries such as "Get total sales for January 2025." A small model might provide faster response times with lower compute cost.
    • Large: Select for more complex queries such as "Show the average sales of the top 5 performing products in Q1 2023 grouped by region." A large model might provide more accuracy but at the cost of higher latency and compute cost.
  5. For Dialect, select one of the following options.
    • SQLite: Select to generate SQL queries that align with SQLite syntax rules. For example: SELECT * FROM users LIMIT 5;
    • Oracle SQL: Select to generate queries that align with Oracle SQL syntax rules. For example: SELECT * FROM users FETCH FIRST 5 ROWS ONLY;

      This option ensures that the generated SQL is fully compatible with the syntax and execution environment of an Oracle Database.

  6. (Optional) For In-context learning examples, select one of the following options to provide examples of natural language queries that users might ask in the context of the schema that's provided, and the expected SQL queries to generate.
    • Inline: Enter a string that contains example questions in natural language and the expected SQL queries.

      For example:

      Question: Show all employees who were born in CA.
Oracle SQL: SELECT * FROM Employees WHERE BIRTHSTATE = 'CA';
    • Choose from Object Storage: Select a compartment and a bucket. Then select the .txt file that contains examples of questions and answers in the context of the database schema.
    • None: No examples to provide.
  7. (Optional) For Database tool connection, select a compartment and then select a connection from the menu.

    To ensure that the selected connection works, select Test connection.

    A connection is necessary only if you want to enable SQL execution or self-correction during a chat session.

    Tip

    If you don't want to use a connection on this tool after you have selected one, select x at the end of the menu to remove the connection.
  8. (Optional) For Enable SQL execution, select to turn on or turn off SQL execution.

    When SQL execution is enabled, the agent generates the SQL query statement, runs the query, and sends the response to the user during the chat session. Only SELECT queries including join, multiple condition, and aggregation are generated and executed. If the execution fails, the agent returns a database execution error with the ORA code (for example, ORA-00933) along with the generated SQL query.

    Tip

    To store results that are larger than 100 rows in an Object Storage bucket, select Enable storage of large output results in the agent endpoint.
  9. (Optional) For Enable SQL correction, select to turn on or turn off self-correction.

    Enable self-correction to correct the query if an error returns during execution. Consider not enabling self-correction for faster execution on simpler queries.

  10. (Optional) For Custom instructions, enter text that prompts the agent to behave in a more specific way.

    For example:

    Always use aggregators such as COUNT, SUM, AVG, MIN, MAX in Oracle SQL queries that contain GROUP BY.

  11. (Optional) For Description of tables and columns, select one of the following options to provide more detailed descriptions of tables and columns used in the database.
    • Inline: Enter a string.

      For example:

      birthYear      Year employee was born
birthMonth     Month employee was born
    • Choose from Object Storage: Select a compartment and a bucket. Then select the .txt file that contains descriptive text for the database tables and columns.
    • None: No description to provide.
  12. Select Create tool.
Tip

Perform one of the following actions:

  • If you're creating an agent, go back to Creating an Agent in Generative AI Agents to create another tool or an endpoint.
  • If you added the tool to an existing agent, after the tool is active, from the agent's detail page, select Launch chat to chat with the agent using this tool.
  • If you created the agent without an endpoint, when you're ready to use the agent, create an endpoint for this agent.