Agentes de Banco de Dados — Guia do Usuário

Um Agente de Banco é uma conexão somente-leitura que o chat do DATTA usa para responder perguntas em linguagem natural consultando um banco de dados: você pergunta "quantos pedidos foram cancelados em agosto?", o modelo escreve a consulta na linguagem do banco, a plataforma a executa e a resposta volta em texto. O agente descreve ao modelo o que existe no banco (tabelas, colunas, relacionamentos) e o que ele pode perguntar.

Este guia cobre o cadastro e o uso dos agentes, incluindo a variante em Neo4j (Cypher), que consulta o cadastro CNPJ carregado na própria plataforma.

Onde você cadastra agentes

A tela é Processar›Agentes de Banco de Dados. Ela é a mesma tela de Sistema›Data Layer›Servidores de Dados, já filtrada nos servidores do tipo JDBC: um Agente de Banco é um servidor JDBC do cadastro de servidores de dados da plataforma, o mesmo cadastro onde ficam os servidores Neo4j, OpenSearch e Trino. Nela você lista, cria, edita, testa a conexão e desativa agentes. Cada agente tem:

Testar e salvar abre uma conexão real antes de gravar: se o banco não responder ou recusar a credencial, nada é gravado e a causa aparece no diálogo. Depois, Testar no cartão repete o teste. Um agente ativo aparece no chat como ferramenta disponível; o modelo o escolhe pelo nome e pelas instruções.

Quem tem as permissões de agentes (JDBC_VIEW, JDBC_CREATE, JDBC_DELETE) vê e gerencia só os servidores JDBC; os demais tipos de servidor são do administrador.

Os agentes que existiam antes desta tela ser unificada foram migrados sozinhos, na atualização da plataforma, com o mesmo identificador, as mesmas instruções e a mesma senha — quem já usava um agente no chat não precisa fazer nada. Um agente antigo sem driver associado chega inativo: associe um driver aprovado e ative-o.

Como o chat usa um agente

Quando você o seleciona — ou quando ele é fonte de um contexto no escopo. Um agente marcado como fonte relacional no cadastro de um contexto entra sozinho sempre que esse contexto está no escopo da conversa (seletor de Contextos e workspace); contexto desligado não leva os agentes dele. Fora disso, sem agente selecionado no chat, a ferramenta de consulta a agentes (jdbc_lookup) não é oferecida ao modelo, o catálogo de dados do prompt não lista agente nenhum e a busca não toca agente nenhum. Com um ou mais agentes selecionados, apenas eles podem ser consultados — pedido para outro agente é recusado com o motivo. (Até 18/09/2026 todos os agentes cadastrados entravam em toda pergunta, e a varredura deles custava até 8 s por mensagem mesmo quando a resposta estava num contexto.)

1. Você ativa o agente no seletor de agentes do chat e faz a pergunta.
2. O modelo recebe o esquema descoberto (tabelas e colunas, ou labels e propriedades) e as regras de geração da linguagem do agente — e pode reler o modelo de dados a qualquer momento pela ferramenta jdbc_schema (dialeto, tabelas/labels, relacionamentos), também restrita ao agente selecionado.
3. A consulta gerada passa por um validador de leitura antes de tocar o banco: qualquer escrita, DDL ou comando administrativo é recusado com a razão em português, e o modelo tenta de novo.
4. O resultado (limitado em linhas) volta ao modelo, que redige a resposta.

Se o serviço de agentes estiver fora do ar ou o agente não existir mais, a consulta é recusada dizendo isso — nunca cai no validador da linguagem errada.

Toda consulta abre a conexão em modo somente-leitura. O usuário do banco cadastrado no agente deve ter apenas permissão de leitura — o validador é defesa em profundidade, não a única barreira.

Busca textual nos agentes

Além das consultas geradas pelo modelo, a busca do chat e a busca global procuram o termo digitado nas colunas de texto de cada tabela do agente, sem diferenciar maiúsculas de minúsculas. Essa busca é montada no dialeto do banco do agente: a citação de nomes (colchetes no SQL Server, crases no MySQL, MariaDB e Impala, aspas duplas nos demais) e o limite de linhas (TOP, FETCH FIRST ou LIMIT) seguem o que cada banco aceita. Até 25/09/2026 ela usava sempre aspas duplas e LIMIT, e em SQL Server, MySQL, MariaDB, Impala e Teradata voltava vazia sem aviso.

• Prazo de 4 segundos por busca. A varredura das tabelas para ao atingir o prazo, a consulta em andamento é cancelada no banco e o que já foi achado volta marcado como parcial. O tempo de espera por uma conexão livre e o de leitura do esquema não entram nessa conta.
• Falha visível. Tabelas em que a busca falha (sem permissão, tipo de coluna que o banco não compara) são somadas num único aviso no log do serviço de agentes. Se a busca falhar em todas as tabelas, a resposta traz a mensagem de erro em vez de "nenhum resultado".
• Termo literal. % e _ no termo são procurados como caracteres comuns, não como curingas.
• Os tipos cadastrados só por API como hive2 e mssql usam o dialeto genérico (aspas duplas e LIMIT); prefira impala e sqlserver.

Esquema do agente: tabela nova e banco fora do ar

O esquema descoberto (tabelas e colunas, ou labels e propriedades) fica guardado em memória no serviço de agentes por 10 minutos, e é o mesmo para o chat, a busca textual e o catálogo. Por isso:

• Uma tabela nova no banco leva até 10 minutos para aparecer no chat. Para não esperar, clique em Editar no cartão do agente e depois em Testar e salvar: salvar descarta o esquema guardado e a próxima pergunta já lê o banco de novo. (Antes de 25/09/2026 o esquema ficava 60 segundos em memória, mas a busca textual o relia do banco a cada chamada.)
• Banco fora do ar não vira "nenhum resultado". Se o esquema não puder ser lido (banco desligado, rede, credencial recusada), a busca responde "Esquema indisponível" em vez de zero linhas, e no construtor de painéis os seletores de tabela e de campos mostram a mesma mensagem. O chat continua recebendo o agente, com a linguagem e as regras de geração, mas sem tabelas. A falha fica lembrada por 60 segundos, para que cada pergunta não espere de novo a conexão; editar e salvar o agente também descarta essa lembrança.

Neo4j (Cypher, somente-leitura)

O tipo Neo4j (Cypher) existe para um caso decidido explicitamente: os agentes de exemplo sobre o cadastro CNPJ que a própria plataforma carrega no grafo. Ele não é o caminho de integração de dados com o Neo4j (isso continua sendo o conector nativo do DATTA Extract) nem substitui a consulta por contexto do copilot — é leitura interativa pelo chat.

O que muda em relação a um agente relacional:

• O modelo gera Cypher, não SQL; a tradução SQL do driver fica desligada.
• Labels fazem o papel de tabelas e propriedades o de colunas. O campo Tabelas vira Labels; o campo Schema não se aplica.
• Label ou propriedade com espaço vai entre crases: `(s:Situacao Cadastral)`.
• Toda consulta termina com LIMIT; a paginação é SKIP n LIMIT m.
• O esquema descoberto inclui os relacionamentos do grafo com o nome exato (ex. (Empresa)-[:TEM_ESTABELECIMENTO]->(Estabelecimento)) — sem isso o modelo inventaria nomes de aresta.
• O validador recusa CREATE, MERGE, SET, DELETE, REMOVE, DROP, LOAD CSV, USE, CALL … IN TRANSACTIONS e procedimentos apoc.* / dbms.*; só passam MATCH, OPTIONAL MATCH, WITH, UNWIND, RETURN e os procedimentos de esquema (db.schema.*, db.labels, db.relationshipTypes, db.propertyKeys).
• A sessão abre em modo READ no driver: mesmo que algo escapasse do validador, o banco não escreve.
• Testar conexão executa RETURN 1 no banco pedido — prova que a sessão de leitura executa Cypher, não só que a porta abriu.

Os três agentes de exemplo

A instalação registra três agentes apontando para o banco cnpj do Neo4j da plataforma (o passo pode ser pulado com a opção correspondente do instalador):

A descrição de cada agente traz o modelo do grafo (chaves empresaCnpj — raiz de 8 dígitos — e estabelecimentoCnpj, arestas TEM_ESTABELECIMENTO, TEM_SOCIEDADE_PESSOA, ASSOCIADA_A_EMPRESA, TEM_CNAE, TEM_SITUACAO_CADASTRAL, TEM_SIMPLES, TEM_MEI, ESTA_EM_MUNICIPIO) e três perguntas-exemplo. O registro é idempotente por nome: rodar o passo de novo atualiza os agentes no lugar, sem duplicar.

Credencial: uma segunda cópia da senha do Neo4j

Os agentes de exemplo usam a mesma senha do Neo4j da plataforma, gravada cifrada no cadastro do agente. É a segunda cópia de uma credencial de sistema, e vale saber disso:

• A senha nunca fica em repositório nem em arquivo de configuração legível: o instalador a lê do ambiente da instalação no momento do registro.
• O agente só lê (sessão READ + validador Cypher), mas a credencial é a de sistema. Se você trocar a senha do Neo4j, rode o registro dos agentes de novo — até lá, Testar conexão falha nos três.
• Quem prefere uma credencial dedicada pode criar no Neo4j um usuário com papel reader e editar os três agentes para usá-lo.

Pré-requisito: driver aprovado

O tipo Neo4j exige o driver Neo4j (Cypher, somente-leitura) aprovado em Sistema›Drivers JDBC. O instalador o baixa junto dos demais drivers oficiais, conferindo a integridade do pacote; numa instalação sem saída para a internet, envie o arquivo do driver manualmente pela mesma tela e rode o registro dos agentes de novo.

Verificar que funcionou

1. Em Sistema›Drivers JDBC, o driver Neo4j aparece como aprovado.
2. Em Processar›Agentes de Banco de Dados, os três agentes CNPJ existem e Testar conexão responde com sucesso.
3. No chat, ative "CNPJ — Empresas e Estabelecimentos" e pergunte "quantas empresas de porte MICRO EMPRESA existem em São Paulo?" — a resposta é um número, e a consulta Cypher gerada aparece no detalhe da ferramenta.
4. Peça algo que escreva ("crie um nó de teste"): a ferramenta recusa com a mensagem "Cláusula proibida em consulta somente-leitura: CREATE" e o modelo explica que o agente é de leitura.

Limites

• Sem algoritmos de grafo (GDS) e sem APOC: é leitura de propriedades e travessia de arestas por Cypher comum.
• A busca textual do agente (usada pela busca global) compara com toLower(...) CONTAINS, sem curinga.
• Consultas muito amplas em labels grandes (o CNPJ tem dezenas de milhões de nós) dependem do LIMIT que o modelo é instruído a colocar; prefira perguntas com filtro (município, porte, CNAE, CNPJ raiz).