Agents

Connect a database

Register a read-only PostgreSQL, MySQL or MariaDB connection so an agent can answer callers from live data, and follow it from Reading schema to Ready.

A database connection lets an agent answer from your own data during a conversation. You register the connection once, EchoNova reads the schema and drafts a list of questions the database can answer, and you approve the ones the agent may use. This page covers the connection itself. Approving the questions is Review and approve database questions, and what happens to your connection string is Database tool security.

A database is not a row in the workspace tool library the way a webhook tool or an imported OpenAPI document is. Tools overview explains how the kinds differ.

What you need

  • Membership of the workspace. The database controls need access to the workspace and no extra permission, so anyone in it can connect a database or delete one.
  • A PostgreSQL, MySQL or MariaDB database reachable over TLS. Those three engines are the whole list today.
  • A database user with read-only access. Read Database tool security before you choose one.
  • A connection string in SQLAlchemy form with an async driver, shaped like postgresql+asyncpg://user:pass@host:5432/db?sslmode=require.
  • One or two sentences about the business. Drafting reads them, and the connection cannot be registered without them.

Steps

Step 1: Open the Add Tool form

On the agent, open the Tools tab and press Add Tool. In the dialog headed Add Tool, choose the Database tab.

Step 2: Name the connection

Name is required and holds up to 120 characters. It is the title every table and sheet shows, instead of the host and database name.

Step 3: Choose the engine

Engine lists MySQL, PostgreSQL and MariaDB in that order. MySQL is preselected, so change it if your database is Postgres or MariaDB. It has to match the database you are pointing at.

Step 4: Paste the connection string

Connection string is required and holds up to 2000 characters. The field is masked as you type. Point it at your read-only user and keep TLS on.

The string is sealed as it arrives and no screen or response returns it afterwards. Keep your own copy: changing it means registering a new connection.

Step 5: Describe the business

Description is the text that steers the questions EchoNova drafts. Write what the business does and what callers usually ask about.

The form labels this field "(Optional)" and counts up to 500 characters. It is required: submitting with it empty fails.

Step 6: Press Test And Connect

Test And Connect seals the connection string, connects to your database over TLS, checks whether the user is read-only, and starts drafting questions. The connection appears immediately with the status Reading schema….

Sample values sent to the AI while drafting offers Masked (fake values) and Raw (real rows). Drafting uses masked values today whichever one you pick, so questions are drafted from your schema and fake samples. To keep a table out of drafting altogether, do not grant the read-only user access to it.

Get it right

The description is the only thing that tells drafting what this database is for. Name the business, the things callers ask about, and the words they use for them.

Recommended

Online pharmacy in the UAE. Callers ask where their order is, whether a medicine
is in stock at a branch, and what a previous order contained. They say "parcel",
"prescription" and "branch".

Less effective

Our main database.

What happens next

Registering from an agent attaches the connection to that agent at once: it is added to the agent's database list, database questions are switched on for that agent, and the agent is saved without a further click. Registering it is the act of giving it to the agent.

The connection then appears in the agent's tools table with the type Database, the host and database string as its endpoint, and a status. It also appears on the Tool Library page, with a chip counting its questions and a TLS chip that fills in once TLS is verified.

While a connection is pending the list refreshes every 5 seconds and stops once nothing is pending, so the status changes without a reload.

Nothing reaches a conversation yet. A new connection has no approved question, and only approved questions reach the agent. Once the status is Ready, go to Review and approve database questions.

The three states

Status Pill in the portal What it means
pending Reading schema… EchoNova is reading the schema and drafting questions. There is nothing to review yet
ready Ready Drafting finished. The questions are listed for review
failed Couldn't connect Connecting or drafting failed. The reason is shown on the connection

Only a Ready connection reaches a conversation. One that is not ready is skipped, and an agent left with no usable connection simply has no database to query.

Limits

Limit Value Applies to
Name 120 characters Registering
Connection string 2000 characters Registering
Description 500 characters Registering
Engines postgresql, mysql, mariadb The whole feature today
Connections per connection string 1 per workspace Registering the same string twice
Reading the schema and drafting 30 seconds Registering and resyncing
Status refresh Every 5 seconds while pending The tools screens
Editing a connection string Not offered. Register a new connection The whole lifetime of a connection

Troubleshooting

"Could not connect the database."

The message under the Add Tool form when registering fails. The common cause is an empty Description, which the form allows and the request refuses. The others are a database EchoNova could not reach, a TLS handshake that failed, and a connection string the engine could not read. Fill in the description, check the host and TLS, then submit again.

The status is Couldn't connect

Connecting or drafting failed. Open the connection: the reason is printed in a red box under the header. Fix the cause and press Resync, or delete the connection and register it again.

"Duplicate value for connection string"

This workspace already has a connection with that exact string. Use the existing connection instead of a second one: the same connection can be attached to as many agents as you like.

The status stays at Reading schema…

Drafting has not finished, so no questions are listed. Press Resync to run it again. If it is still pending after a resync, delete the connection and register it again.

The connection is Ready but the agent never uses it

A connection with no approved question gives the agent nothing. Approve at least one, and check the connection is attached to the agent you are testing rather than only present in the workspace.

FAQ

Can I see the connection string again?

No. It is sealed on the way in and no screen or response returns it. The portal shows the host and database part only, never the credentials.

Can two agents share one database?

Yes. Each agent holds its own list of the connections it may query, and the same connection can appear in several of those lists.

Does EchoNova write to my database?

No. Every approved question is a read. See Database tool security.

What does deleting a connection do?

It removes the connection and its questions, and the agent stops reaching them. It cannot be undone, and the connection string goes with it. An agent that still lists a deleted connection is unaffected; the connection is simply skipped.

Where else can I manage a connection?

The Tool Library page lists every database in the workspace alongside the other tools, with the same review sheet behind the row menu. Registering a new one happens from an agent's Add Tool form.