Database Agents — User Guide

A Database Agent is a read-only connection the DATTA chat uses to answer natural-language questions by querying a database: you ask "how many orders were cancelled in August?", the model writes the query in the database's language, the platform runs it and the answer comes back as text. The agent describes to the model what the database holds (tables, columns, relationships) and what can be asked.

This guide covers creating and using agents, including the Neo4j (Cypher) variant, which queries the CNPJ registry loaded into the platform itself.

Where you create agents

The screen is Processar›Agentes de Banco de Dados. It is the same screen as Sistema›Data Layer›Servidores de Dados, already filtered to JDBC servers: a Database Agent is a JDBC server in the platform's data server registry, the same registry that holds the Neo4j, OpenSearch and Trino servers. There you list, create, edit, test and deactivate agents. Each agent has:

Testar e salvar (test and save) opens a real connection before saving: if the database does not answer or refuses the credential, nothing is saved and the cause is shown in the dialog. Afterwards, Testar on the card repeats the test. An active agent appears in the chat as an available tool; the model picks it by name and instructions.

Users holding the agent permissions (JDBC_VIEW, JDBC_CREATE, JDBC_DELETE) see and manage only the JDBC servers; the other server types belong to the administrator.

Agents that existed before this screen was unified were migrated automatically during the platform update, keeping the same identifier, instructions and password — whoever already used an agent in the chat does not need to do anything. An old agent without an associated driver arrives inactive: associate an approved driver and activate it.

How the chat uses an agent

When you select it — or when it is a source of a context in scope. An agent ticked as a relational source in a context's registration enters by itself whenever that context is in the conversation scope (Contexts selector and workspace); a disabled context does not bring its agents. Otherwise, with no agent selected in the chat, the agent query tool (jdbc_lookup) is not offered to the model, the prompt's data catalogue lists no agent and the search touches no agent. With one or more agents selected, only those can be queried — a request for another agent is refused with the reason. (Until 2026-09-18 every registered agent entered every question, and sweeping them cost up to 8 s per message even when the answer was in a context.)

1. You enable the agent in the chat's agent selector and ask the question.
2. The model receives the discovered schema (tables and columns, or labels and properties) and the generation rules for the agent's language — and can re-read the data model at any time through the jdbc_schema tool (dialect, tables/labels, relationships), also restricted to the selected agent.
3. The generated query goes through a read-only validator before touching the database: any write, DDL or administrative command is refused with the reason in Portuguese, and the model tries again.
4. The result (row-limited) goes back to the model, which writes the answer.

If the agent service is down or the agent no longer exists, the query is refused saying so — it never falls into the wrong language's validator.

Every query opens the connection in read-only mode. The database user registered in the agent should have read permission only — the validator is defence in depth, not the only barrier.

Text search in agents

Besides the queries the model generates, the chat search and the global search look for the typed term in the text columns of every table of the agent, case-insensitively. That search is built in the dialect of the agent's database: name quoting (brackets in SQL Server, backticks in MySQL, MariaDB and Impala, double quotes elsewhere) and the row limit (TOP, FETCH FIRST or LIMIT) follow what each database accepts. Until 2026-09-25 it always used double quotes and LIMIT, and in SQL Server, MySQL, MariaDB, Impala and Teradata it came back empty without warning.

• 4-second deadline per search. The table scan stops when the deadline is reached, the running query is cancelled on the database and what was already found comes back flagged as partial. Waiting for a free connection and reading the schema do not count towards it.
• Visible failure. Tables where the search fails (no permission, a column type the database cannot compare) are summed up in a single warning in the agent service log. If the search fails on every table, the response carries the error message instead of "no results".
• Literal term. % and _ in the term are searched as plain characters, not as wildcards.
• The types registered only through the API, such as hive2 and mssql, use the generic dialect (double quotes and LIMIT); prefer impala and sqlserver.

Agent schema: new tables and a database that is down

The discovered schema (tables and columns, or labels and properties) is kept in memory by the agent service for 10 minutes, and it is the same for the chat, the text search and the catalog. Therefore:

• A new table in the database takes up to 10 minutes to show up in the chat. To skip the wait, click Editar (edit) on the agent card and then Testar e salvar (test and save): saving discards the stored schema and the next question reads the database again. (Before 2026-09-25 the schema stayed 60 seconds in memory, but the text search read it again from the database on every call.)
• A database that is down no longer becomes "no results". If the schema cannot be read (database off, network, credential refused), the search answers "Esquema indisponível" (schema unavailable) instead of zero rows, and in the panel builder the table and field selectors show the same message. The chat still receives the agent, with the language and the generation rules, but without tables. The failure is remembered for 60 seconds, so that each question does not wait for the connection again; editing and saving the agent also discards it.

Neo4j (Cypher, read-only)

The Neo4j (Cypher) type exists for one explicitly decided case: the sample agents over the CNPJ registry the platform itself loads into the graph. It is not the data-integration path to Neo4j (that remains the native DATTA Extract connector) nor a replacement for the copilot's per-context queries — it is interactive reading through the chat.

What differs from a relational agent:

• The model generates Cypher, not SQL; the driver's SQL translation is off.
• Labels play the role of tables and properties that of columns. The Tables field becomes Labels; the Schema field does not apply.
• Labels or properties containing spaces go between backticks: `(s:Situacao Cadastral)`.
• Every query ends with LIMIT; pagination is SKIP n LIMIT m.
• The discovered schema includes the graph's relationships with their exact names (e.g. (Empresa)-[:TEM_ESTABELECIMENTO]->(Estabelecimento)) — without them the model would invent edge names.
• The validator refuses CREATE, MERGE, SET, DELETE, REMOVE, DROP, LOAD CSV, USE, CALL … IN TRANSACTIONS and apoc.* / dbms.* procedures; only MATCH, OPTIONAL MATCH, WITH, UNWIND, RETURN and the schema procedures (db.schema.*, db.labels, db.relationshipTypes, db.propertyKeys) pass.
• The session opens in READ mode in the driver: even if something slipped past the validator, the database does not write.
• Testar conexão runs RETURN 1 on the requested database — proof that the read session executes Cypher, not just that the port opened.

The three sample agents

The installation registers three agents pointing at the platform Neo4j's cnpj database (the step can be skipped with the corresponding installer option):

Each agent's description carries the graph model (keys empresaCnpj — the 8-digit root — and estabelecimentoCnpj; edges TEM_ESTABELECIMENTO, TEM_SOCIEDADE_PESSOA, ASSOCIADA_A_EMPRESA, TEM_CNAE, TEM_SITUACAO_CADASTRAL, TEM_SIMPLES, TEM_MEI, ESTA_EM_MUNICIPIO) and three sample questions. Registration is idempotent by name: running the step again updates the agents in place, without duplicates.

Credential: a second copy of the Neo4j password

The sample agents use the same password as the platform's Neo4j, stored encrypted in the agent record. It is the second copy of a system credential, and that is worth knowing:

• The password never lives in a repository or in a readable configuration file: the installer reads it from the installation environment at registration time.
• The agent only reads (READ session + Cypher validator), but the credential is the system one. If you change the Neo4j password, run the agent registration again — until then Testar conexão fails on all three.
• If you prefer a dedicated credential, create a Neo4j user with the reader role and edit the three agents to use it.

Prerequisite: approved driver

The Neo4j type requires the Neo4j (Cypher, somente-leitura) driver approved in Sistema›Drivers JDBC. The installer downloads it along with the other official drivers, checking the package integrity; in an installation without internet access, upload the driver file manually on the same screen and run the agent registration again.

Checking it works

1. In Sistema›Drivers JDBC, the Neo4j driver shows as approved.
2. In Processar›Agentes de Banco de Dados, the three CNPJ agents exist and Testar conexão succeeds.
3. In the chat, enable "CNPJ — Empresas e Estabelecimentos" and ask "how many MICRO EMPRESA companies are there in São Paulo?" — the answer is a number, and the generated Cypher shows in the tool detail.
4. Ask for something that writes ("create a test node"): the tool refuses with the message "Cláusula proibida em consulta somente-leitura: CREATE" and the model explains the agent is read-only.

Limits

• No graph algorithms (GDS) and no APOC: it is property reading and edge traversal through plain Cypher.
• The agent's text search (used by global search) compares with toLower(...) CONTAINS, without wildcards.
• Very broad queries on large labels (CNPJ has tens of millions of nodes) depend on the LIMIT the model is instructed to add; prefer filtered questions (municipality, size, CNAE, CNPJ root).