Diretrizes da Ferramenta SQL para Agentes de IA Generativa

A ferramenta SQL em Agentes de IA Generativa suporta o Oracle Database (Base Database e Autonomous Database).

Crie as tabelas e carregue dados no banco de dados de sua preferência. Se você estiver usando a ferramenta SQL para gerar instruções de consulta e, em seguida, corrigir automaticamente ou executar as consultas, deverá configurar uma conexão de ferramentas de banco de dados com o banco de dados que contenha dados para a consulta e a execução. Para obter ajuda com a criação de uma conexão, consulte Criar Conexão do Serviço Database Tools (Diretrizes).

Talvez você não precise criar tabelas no banco de dados se estiver usando apenas a ferramenta SQL para gerar instruções de consulta e não estiver permitindo que a ferramenta corrija ou execute consultas SQL automaticamente. No entanto, você ainda precisará fornecer o esquema da tabela de banco de dados ao criar a ferramenta SQL em um agente.

Um esquema de banco de dados válido deve ser fornecido quando você adiciona uma ferramenta SQL a um agente nos Agentes de IA Generativa. A criação da ferramenta SQL falhará na etapa de validação se o esquema for inválido.

Um esquema válido é um blueprint de banco de dados bem estruturado que inclui o seguinte:

• Tabelas: Defina entidades (por exemplo, Customers, Orders)

• Colunas: Especifique atributos (por exemplo, CustomerID, OrderDate)

• Chaves Primárias: Identifique linhas exclusivamente (por exemplo, CustomerID)

• Chaves Estrangeiras: Tabelas de links (por exemplo, CustomerID em Orders faz referência a Customers).

• Restrições: Imponha regras (por exemplo, NOT NULL, UNIQUE).

Exemplo de um esquema válido:

CREATE TABLE Employees (
    EmployeeID INT PRIMARY KEY,
    Name VARCHAR(100) NOT NULL,
    DepartmentID INT,
    HireDate DATE NOT NULL,
    FOREIGN KEY (DepartmentID) REFERENCES Departments(DepartmentID)
);

Um esquema bem estruturado garante a integridade e a eficiência dos dados.

Exemplo de um esquema inválido:

CREATE TABLE Employees (
    EmployeeID,
    Name VARCHAR(100),
    DepartmentID INT,
    HireDate DATE
);

Um esquema inválido sem estrutura pode levar a possíveis inconsistências e ineficiências de dados. No exemplo, o esquema é inválido porque:

• Estão faltando chaves primárias no esquema (EmployeeID, DepartmentID).
• Um tipo de dados para EmployeeID está ausente.

Ao criar uma ferramenta SQL, você pode selecionar entre o uso de um modelo pequeno ou grande.

Um modelo pequeno fornece tempos de resposta mais rápidos. Você selecionaria um modo pequeno para consultas simples, como "Obter vendas totais para janeiro de 2025".

Um modelo grande fornece mais precisão, mas ao custo de maior latência. Você selecionaria um modelo grande para consultas mais complexas, como "Mostrar a média de vendas dos 5 produtos com melhor desempenho em Q1 2023 agrupados por região".

A ferramenta SQL suporta os dialetos Oracle SQL e SQLite.

Com base em seu dialeto preferido, o agente pode gerar consultas alinhadas com as regras sintáticas do Oracle SQL ou SQLite.

Exemplos de diferenças de sintaxe entre SQLite e Oracle SQL:

Oracle: SELECT * FROM users FETCH FIRST 5 ROWS ONLY;
SQLite: SELECT * FROM users LIMIT 5;

Oracle: SELECT 'Hello' || ' World' FROM dual;
SQLite: SELECT 'Hello' || ' World';

Verifique se você tem os seguintes requisitos configurados se estiver ativando e usando a ferramenta SQL para executar as consultas SQL após gerar as instruções SQL:

• Para que a regra de entrada seja configurada na sub-rede privada de um banco de dados, consulte Requisitos de Rede (sem suporte entre regiões e entre tenancies).

• Um vault no OCI Vault é necessário para armazenar o segredo da senha do banco de dados. Crie o vault no mesmo compartimento do banco de dados.

• Se o banco de dados autônomo estiver ativado para autenticação mTLS (Mutual TLS), você precisará fazer download da wallet e extrair um arquivo. Consulte Requisitos de Segurança de Wallet.

Você pode ativar uma ferramenta SQL para corrigir automaticamente e executar uma consulta depois de gerar a instrução SQL. Quando a execução de SQL ou a autocorreção está ativada, é necessária uma conexão do serviço Database Tools com o banco de dados que contém dados para a consulta e a execução.

Para obter ajuda com a criação de uma conexão, consulte Criar Conexão do Serviço Database Tools (Diretrizes).

Os buckets do Object Storage podem ser usados para conter arquivos de entrada para a ferramenta SQL. Se a execução de SQL estiver ativada em uma ferramenta SQL, os arquivos de saída da execução de consultas SQL poderão ser armazenados no Object Storage.

Certifique-se de conceder aos usuários acesso a todos os recursos dos Agentes de IA Generativa, conforme descrito em Adicionando Políticas Antes de Usar o Serviço.

Revise também as seções a seguir e conclua as tarefas necessárias para usar uma função específica em um agente com uma ferramenta SQL (por exemplo, ative a execução SQL).

• Serviço Object Storage
• Execução de SQL, Autocorreção e Armazenamento de Saída

Allow any-user to inspect buckets in compartment <compartment-name> where all { target.bucket.name = '<bucket-name>', request.principal.type='genaiagent' }

Allow any-user to read objects in compartment <compartment-name> where all { target.bucket.name = '<bucket-name>', request.principal.type='genaiagent' } 

Allow any-user to use database-tools-connections in compartment <compartment-name> where request.principal.type='genaiagent'

Allow any-user to read database-tools-family in compartment <compartment-name> where request.principal.type='genaiagent'

Allow any-user to read secret-family in compartment <compartment-name> where request.principal.type='genaiagent'

Allow any-user to {BUCKET_INSPECT, BUCKET_READ, OBJECT_INSPECT, OBJECT_READ, OBJECT_CREATE, OBJECT_OVERWRITE, PAR_MANAGE} in compartment <compartment-name> where all { target.bucket.name = '<bucket-name>', request.principal.type='genaiagent' } 

Você pode fornecer contexto sobre o esquema do banco de dados na forma de perguntas de exemplo que os usuários podem fazer e as consultas SQL esperadas como respostas de exemplo. Exemplos de aprendizado contextual são úteis para responder consultas de usuários semelhantes.

Exemplos:

Question: Show all employees who were born in CA.
Oracle SQL: SELECT * FROM Employees WHERE BIRTHSTATE = 'CA';

Question: Get the employeeid of employees who joined in 2020.
Oracle SQL: SELECT employeeID FROM Employees WHERE hireDate = '2020';

Você pode fornecer um ou mais prompts para modificar o comportamento do agente.

Por exemplo:

Always use aggregators such as COUNT, SUM, AVG, MIN, and MAX in Oracle SQL queries that contain GROUP BY.
If the Oracle SQL query contains ORDER BY, then show the ORDER BY metric in the SELECT clause as well.
If all columns must be returned, use the (*) notation.
Ensure to include all relevant WHERE filtering conditions even when the number of conditions is larger than those of in-context learning examples.

A adição de descrições de tabelas e colunas pode melhorar a precisão da consulta, tratar a ambiguidade e ajudar o modelo a entender melhor consultas complexas e termos específicos. Por exemplo, descrever a coluna status em Orders como Order status: pending, shipped, or delivered ajuda o modelo a interpretá-la corretamente nas consultas do usuário.

Por exemplo:

Description of the important tables in the schema:

Employees         Employee names and other information
Departments       Department names and other information 

Description of the important columns of the tables in the schema:

EMPLOYEES TABLE

employees.employeeID     A unique code assigned to each employee. employeeID links the data in this file with records in the other files.
employees.departmentID   A unique code that identifies the department an employee belongs to
employees.birthYear      Year employee was born
employees.birthMonth     Month employee was born
employees.birthState     State where employee was born
employees.birthCity      City where employee was born
employees.nameFirst      Employee's first name
employees.nameLast       Employee's last name
employees.nameMiddle     Employee's middle name
employees.hireDate       Year employee joined the company

---------------------------------------------------------------------
DEPARTMENTS TABLE

department.departmentID    A unique code assigned to each department
department.departmentName  Name of the department
department.locationID      Unique code that identifies the location of a department
department.managerID       Unique code that identifies the department's manager