ObeliskDB docs Home Whitepaper Console

Agent sessions

An agent session is how ObeliskDB makes agent writes safe by construction. Every Obi conversation — and every external MCP connection — runs inside one: a first-class object with an enforced budget, a full audit trail, and an isolated branch created the moment the agent first writes. The pull request, applied to data.

The propose → review → merge flow

An agent doesn't write to your data. It writes to a copy, and you decide what ships.

  1. 1. Read freely. Until the agent's first data-modifying statement, reads run against live data (which is identical anyway).
  2. 2. First write branches. The first INSERT/UPDATE/DELETE/MERGE/CREATE TABLE automatically creates a zero-copy branch of the target database. From then on, every statement in the session — reads included — is transparently redirected to the branch. The agent sees its own changes; live data is untouched.
  3. 3. You review. The control plane's Review queue shows the session's staged changes: the exact statements it ran, and a row-level diff per changed table (added / removed), or the contents of any new table.
  4. 4. Merge or discard. Merging fast-forwards the source database; discarding drops the branch. Nothing reached production without your approval.
SHOW AGENT SESSIONS;   -- who ran what, on which branch, for how much

Budgets

Each session carries a credit budget (default 25; set OBI_BUDGET_CREDITS, or OBELISK_MCP_BUDGET_CREDITS for MCP). Every statement's estimated cost is charged against it, and once the budget is spent the next statement is refused — in the executor, not by asking the agent to be frugal. An agent that loops cannot spend your month. See Economics in the guarantees.

What agents may never do

Some operations bypass the branch (they aren't table mutations) and would hit live data directly. In an agent session these are refused outright, whatever the agent is instructed to do:

DROP DATABASE / SCHEMA / USER / ROLE / WAREHOUSE
CREATE USER / ROLE / WAREHOUSE
GRANT / REVOKE / ALTER USER
VACUUM / MERGE BRANCH / UNDROP

Ordinary writes still stage on the branch and are fully reviewable; only these irreversible or privileged operations are blocked. A human runs them in the console. This is the structural defense against indirect prompt injection — an instruction hidden in a data cell has nothing to act on. See The guarantees.

One contract, every caller

The same governed-execution path backs Obi and external MCP clients alike. An external coding agent that connects over MCP with no knowledge of any of this still branches on write, is budgeted, is logged, and is blocked from irreversible operations — because the contract is enforced beneath it. That is the point of putting it in the data plane.

Platform agents

Scheduled agents (defined in agents/*.toml) run as one-shot Obi conversations on a cadence — a FinOps watchdog, a data-quality checker, an insight keeper. They run inside agent sessions too: budgeted, audited, and settling on completion (a read-only run closes; a run that wrote leaves its branch for review).