Meet the agent

Behind Databasin One is an agent orchestrator — a loop that holds a conversation with a large language model while handing it carefully scoped tools. This article walks through what that loop looks like, so when you see the agent "thinking" in the UI, you know what's actually happening.

The loop in words

At a high level, every turn goes like this:

1. You send a message.
2. The agent sees your message plus a system prompt describing what it can do and the current data context.
3. The model responds with either:
   • A final text answer (done), or
   • A tool call: "call get_schema on sales_warehouse."
4. Databasin runs that tool and sends the result back to the model.
5. Repeat from step 3 until the model has enough to answer.

The workflow indicator you see in the UI (Reading schema… Planning query… Running query… Analyzing…) is a friendly gloss on which tool is currently executing.

The tools the agent has

There are 12 tools, in two groups.

Data and action tools (5)

These do real work — they touch your warehouse or build artifacts:

• get_schema — list the catalogs, schemas, tables, and columns available.
• get_sample_data — pull a few sample rows (5 by default, up to 20) so the model can see actual values before it writes a complex query.
• execute_sql — run a query and return up to 1000 rows.
• propose_semantic_model — draft a curated semantic model from your tables and business questions.
• refine_semantic_model — adjust that model when you ask for changes.

Skills (7)

Seven pieces of specialist knowledge the agent can consult on demand:

• Query — how to write good analytical SQL for the target engine.
• ECharts — the chart catalog and when to use what.
• Analysis — "this data has two dimensions and one measure → here are sensible chart types."
• Document — how to structure reports and cite sources.
• Semantic search — how to search inside uploaded documents.
• Power BI — how to translate Power BI's DAX into SQL.
• Semantic model — the rules for building a sound semantic model.

Each skill is a structured reference, not an API. The agent reads it when needed, then compacts it away to save tokens. The Skills article covers each one in depth.

The budget

Every conversation has a budget of 3 execute_sql calls. The prompt tells the model this explicitly, and the code enforces it — if the model tries a fourth, the system rejects the call before the query runs and tells the model to answer with what it already has.

Why so tight? SQL is the expensive, slow part. Good analysis rarely needs more than three queries; usually it's one or two carefully composed CTEs. get_schema, get_sample_data, and skill reads are all free — they don't count against the budget.

Which model runs it

Databasin One doesn't hard-code a model. It talks to whichever LLM connector you've selected, which means the same agent can run on Claude or GPT. The loop, the tools, and the 3-query budget are identical either way — a model proxy normalizes the differences between the two providers.

The behavior differs in small ways. Claude tends to batch several tool calls into one turn; GPT calls tools one at a time and gets a gentle nudge to wrap up once it has enough data. You won't usually notice, but it's why the same question can take a slightly different number of steps depending on the model. For how to pick, see Choosing your model.

Cost optimizations under the hood

A handful of things keep this cheap and fast:

• Prompt caching. The system prompt and tool definitions are marked for caching, so repeated turns reuse them instead of re-sending the whole preamble each time.
• Skill compaction. After the model reads a skill once, its content is swapped for a short "already read" placeholder — saving thousands of tokens over a multi-turn conversation. SQL results, sample data, and schemas are never compacted; the model needs those values to reason.
• Parallel first call. The model is encouraged to read a skill and call get_schema in the same first turn instead of serializing them.
• Response caps. Each path (answering, charting, exporting) has its own length cap tuned to what it actually needs.

Where retries and failures show up

• Gateway timeout / network error on the LLM proxy → retried automatically before giving up.
• Truncated response (the model hit its length cap) → automatic recovery from the last SQL result.
• Tool error (bad SQL, missing table) → the agent sees the error and usually self-corrects.
• Query budget exhausted → the agent wraps up with what it has.

If a run truly fails, you get an error bubble with enough detail to retry or report it.

Where to go next