Documentação do Oracle Cloud Infrastructure

Criando uma Ferramenta SQL em Agentes de IA Generativa

Em Agentes de IA Generativa, cada agente deve ter uma ou mais ferramentas. Você pode criar a ferramenta de um agente durante ou após a criação do agente. Para ambas as opções, a criação de uma ferramenta tem as mesmas etapas. Esta seção mostra as etapas para criar uma ferramenta SQL.

Antes de criar uma ferramenta SQL, revise as Diretrizes da Ferramenta SQL para Agentes de IA Generativa e conclua as tarefas necessárias.

Criando uma Ferramenta SQL

  1. Selecione Criar ferramenta e, em seguida, selecione SQL.
  2. Informe um nome e uma descrição para esta ferramenta SQL.
    Uma descrição do esquema do banco de dados nessa ferramenta ajuda o agente a entender melhor como gerar instruções de consulta SQL.
  3. Para Importar configuração de esquema de banco de dados, selecione uma das opções a seguir para fornecer o esquema de banco de dados a ser usado para essa ferramenta. Um esquema é um conjunto de instruções SQL que devem incluir tabelas, colunas, tipos de dados e relacionamentos para definir a organização de objetos no banco de dados.
    • Em Linha: Informe uma string que contenha as instruções SQL. A string deve começar com uma palavra-chave SQL válida, como CREATE e ALTER, ou um parêntese de abertura (.
    • Escolher no Serviço Object Storage: Selecione um compartimento e um bucket. Em seguida, selecione o arquivo .sql que contém as instruções SQL.
  4. Para Personalização de modelo, selecione uma das seguintes opções.
    • Pequeno: selecione para consultas simples, como "Obter vendas totais para janeiro de 2025". Um modelo pequeno fornece tempos de resposta mais rápidos.
    • Grande: Selecione para consultas mais complexas, como "Mostrar a média de vendas dos 5 principais produtos com desempenho em Q1 2023 agrupados por região". Um modelo grande fornece mais precisão, mas ao custo de maior latência.
  5. Para Dialeto, selecione uma das seguintes opções.
    • SQLite: Selecione para gerar consultas SQL alinhadas às regras de sintaxe SQLite. Por exemplo: SELECT * FROM users LIMIT 5;
    • Oracle SQL: Selecione para gerar consultas que se alinham às regras de sintaxe do Oracle SQL. Por exemplo: SELECT * FROM users FETCH FIRST 5 ROWS ONLY;

      Essa opção garante que o SQL gerado seja totalmente compatível com a sintaxe e o ambiente de execução de um Oracle Database.

  6. (Opcional) Para Exemplos de aprendizagem contextual, selecione uma das opções a seguir para fornecer exemplos de consultas de linguagem natural que os usuários podem solicitar no contexto do esquema fornecido e as consultas SQL esperadas a serem geradas.
    • Em Linha: Informe uma string que contenha perguntas de exemplo em linguagem natural e as consultas SQL esperadas.

      Por exemplo:

      Question: Show all employees who were born in CA.
Oracle SQL: SELECT * FROM Employees WHERE BIRTHSTATE = 'CA';
    • Escolher no Serviço Object Storage: Selecione um compartimento e um bucket. Em seguida, selecione o arquivo .txt que contém exemplos de perguntas e respostas no contexto do esquema do banco de dados.
    • Nenhum: Nenhum exemplo a ser fornecido.
  7. (Opcional) Para Conexão da ferramenta de banco de dados, selecione um compartimento e, em seguida, selecione uma conexão no menu.

    Uma conexão só será necessária se você quiser ativar a execução de SQL ou a autocorreção durante uma sessão de chat.

    Para garantir que a conexão selecionada esteja funcionando, selecione Testar conexão.

    Observação

    O teste de conexão só valida se a configuração da conexão com o banco de dados no serviço Database Tools está funcionando corretamente e o banco de dados pode ser acessado. O teste não valida o acesso do agente ao banco de dados. Use políticas para garantir que os Agentes de IA Generativa possam acessar o banco de dados.
    Dica

    Se você não quiser usar uma conexão nesta ferramenta depois de selecionar uma, selecione x no final do menu para remover a conexão.
  8. (Opcional) Para Ativar execução de SQL, selecione para ativar ou desativar a execução de SQL.

    Quando a execução de SQL está ativada, o agente gera a instrução de consulta SQL, executa a consulta e envia a resposta ao usuário durante a sessão de chat. Somente consultas SELECT, incluindo junção, várias condições e agregação, são geradas e executadas. Se a execução falhar, o agente retornará um erro de execução do banco de dados com o código ORA (por exemplo, ORA-00933) junto com a consulta SQL gerada.

    Dica

    Para armazenar resultados maiores que 100 linhas em um bucket do Object Storage, selecione Ativar armazenamento de resultados de saída grandes no ponto final do agente.
  9. (Opcional) Para Ativar correção de SQL, selecione para ativar ou desativar a autocorreção.

    Ative a autocorreção para corrigir a consulta se um erro retornar durante a execução. Considere não ativar a autocorreção para uma execução mais rápida em consultas mais simples.

  10. (Opcional) Para Instruções personalizadas, digite o texto que solicita que o agente se comporte de uma maneira mais específica.

    Por exemplo:

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

  11. (Opcional) Para Descrição de tabelas e colunas, selecione uma das opções a seguir para fornecer descrições mais detalhadas de tabelas e colunas usadas no banco de dados.
    • Em Linha: Informe uma string.

      Por exemplo:

      birthYear      Year employee was born
birthMonth     Month employee was born
    • Escolher no Serviço Object Storage: Selecione um compartimento e um bucket. Em seguida, selecione o arquivo .txt que contém texto descritivo para as tabelas e colunas do banco de dados.
    • Nenhum: Nenhuma descrição a ser fornecida.
  12. Selecione Criar ferramenta.
Dica

Execute uma das seguintes ações:

  • Se você estiver criando um agente, volte para Criando um Agente em Agentes do Serviço Generative AI para criar outra ferramenta ou um ponto final.
  • Se você tiver adicionado a ferramenta a um agente existente, depois que a ferramenta estiver ativa, na página de detalhes do agente, selecione Iniciar chat para conversar com o agente usando essa ferramenta.
  • Se você criou o agente sem um ponto final, quando estiver pronto para usar o agente, crie um ponto final para esse agente.
Observação

Para permitir que um revisor humano monitore e edite uma consulta gerada antes de enviá-la ao usuário, selecione o recurso opcional Ativar humano no loop no ponto final do agente.