Agent database¶

The agent database gives your agent its own structured data — tables of records it can read and write as it works — without you designing a database or writing any SQL. It's for the things a knowledge base can't do: remembering, capturing, and updating individual records over time.

Use it when your agent needs to keep track of things, for example:

Lead capture / CRM — record who reached out, their contact details, and status.
Orders and bookings — take an order or reservation and store it.
Surveys and quizzes — collect answers and scores.
User progress — remember where each user left off.
A structured catalog or FAQ — look up items by field rather than by search.
An event log — append a record every time something happens.

How you set it up¶

You never write table definitions or pick column types. You describe, in plain language, what the agent should keep track of ("remember each customer's name, email, and whether they've been contacted"), and the Builder designs the tables for you and switches on the Database capability. The first time it does this, it confirms with you.

Because it's just another capability, the Database tool sits alongside memory, sub-agents, and the rest in the agent's tools, and can be turned on or off there.

The Data tab¶

Once the database is on, the agent gets a Data tab where you can see and manage everything it has stored — a spreadsheet-like view of your tables:

Browse records with filtering and sorting.
Export a table to CSV.
See how much storage the agent's data is using.

Viewing is always available. Directly editing or deleting individual rows from this view is gated behind a debug mode, because in normal operation the agent — not a human clicking around — is what changes the data. Deletions are soft (records are marked deleted rather than erased), and activity is logged.

Changing the tables of an agent that already has data¶

When the Builder changes the shape of an existing database — a new table, a new column — that change is applied to the agent's live data, so it either lands completely or it does not land at all:

While the change is being applied, the agent is paused. Runs in flight finish first; new ones wait.
If any part of the change fails, the update is reported as failed and the agent stays paused. The version you were running stays the current one. Your records are not touched, and your existing data and conversation history stay readable.
Retrying is safe. Every table change the platform makes is recorded in the agent's own database at the moment it is made, so a retry can tell what already went through: it finishes the parts that did not complete, and never applies the same change twice. This holds whether the change was interrupted before, during or after it landed.

One kind of schema change cannot be undone automatically: building an index without locking the table has to run outside the platform's safety net. If that is interrupted mid-way, the agent stays paused and the update asks for a human to check the result rather than guessing — the platform never retries it blindly.

Self-hosted deployments

Some self-hosted installations run the agent database in a single-tenant mode where the platform cannot prove that a schema change ran exactly once. There, applying a package that adds new database changes to an agent that already exists is refused up front, with an explanation. Creating a new agent from that same package works normally, and so does updating an agent with a package that changes no tables. Donkit's hosted platform is unaffected.

Timestamps on every record¶

Every record automatically keeps track of two moments, so you and your agent always know when things happened without anyone having to set them:

When it was added — the moment the record was first stored. This never changes.
When it was last changed — kept up to date automatically every time the record is edited, so it always reflects the most recent change.

You don't manage these — the platform keeps them accurate on its own, and you can see them in the Data tab.

If your data carries its own meaningful date — an article's publication date, say, or the date an event takes place — that lives in a separate field of its own, apart from when the agent stored the record. This keeps two different questions from getting mixed up: "what did we add today?" versus "what was published today?".

Who can see which records¶

The agent database enforces access automatically, so a published agent's end users only touch data they're allowed to:

End users of a published agent get per-user isolation — each person sees and edits only their own records. This is what makes "remember my progress" or "show my orders" safe when many people use the same agent.
Owners, team members, and admins have privileged access — they can see across all records (this is what powers the Data tab).

For each table you can set an access policy — whether end users can read and/or write it, and whether that applies to their own records only or more broadly. This lets you build, say, a catalog everyone can read but only the agent can update, alongside a per-user orders table.

A new table starts closed to end users. The one exception is a table with an owner column, which starts as "own records only", so each person sees just their own rows. Every other table stays private until the Builder or you open it on purpose, for example making a catalog readable by everyone signed in. That way nobody sees another person's data by accident.

Shared team database¶

A team of agents can share one database besides each agent's own. Its tables are created by the lead agent's Builder, and every member agent reads and writes them.

The same per-table access policy applies — read / write set to none, owner, everyone signed in, or own records only — and the same per-user isolation for end users: a published member agent's end users see only their own records in "own records" tables. Owners, team members, and admins see everything.

The lead's Data tab has a Team mode showing the shared tables, their rows, export, and the access policy editor. The Data button on the Teams page opens it straight away.

An app built for a member agent reads and writes shared tables the same way it reads its own — the Builder does this when you ask for it ("the form saves answers to the team's shared table").

Private admin side, public form side

Keep the team itself unpublished, and publish the collecting agent on its own. Respondents write their own rows through the published agent; the admin agent — and the rest of the team — sees all of them, through the shared database.

Note

Tables that existed before this feature keep working. On first use, each one receives the same default as a new table — own records when the table has an owner column, otherwise closed to end users — which the lead can change afterwards.

Turning it off¶

You can disable the database, which keeps all the data but removes the Database capability from the agent, or permanently delete the data, which requires a typed confirmation to prevent accidents.