data agent + dbt: the handoff pattern

TL;DR

Let the agent read everything in dbt, manifests, docs, test results, but write nothing directly: the agent proposes model changes as diffs or pull requests, and dbt CI is the gate that decides what merges. dbt stays the version-controlled source of truth for transforms; the agent is a very fast junior analyst. It works because dbt's test suite does the verification the agent cannot do reliably itself, turning agent output from a risk into a draft.

data agent + dbt: the handoff pattern

Use this when

• Agents help build, fix, or refactor dbt models
• An agent needs full project context without write access
• You want agent velocity without losing review discipline
• Debugging a failing model with an agent assistant

Not for

• Letting agents merge to main directly
• Agents editing production data outside the dbt project
• Replacing human judgment on data modeling decisions

Steps

1. Give the agent read access to the compiled project artifacts:

# the agent reads these, never writes them
ls target/manifest.json target/catalog.json
# manifest: every model, its SQL, its dependencies, its tests
# catalog: every column, its type, from the warehouse itself

Expected output: the agent can answer which models exist, what columns they have, and what depends on what, without touching the repo.

1. Have the agent draft the change as a unified diff, not as edits:

--- a/models/marts/orders.sql
+++ b/models/marts/orders.sql
@@ -12,6 +12,7 @@
 select
   order_id,
   customer_id,
+  amount_cents / 100.0 as amount_dollars,
   status
 from {{ ref('stg_orders') }}

Expected output: a reviewable diff. The human sees exactly what changes, and the agent cannot accidentally rewrite half the project.

1. Open the change as a pull request so CI runs the real checks:

git checkout -b agent/add-amount-dollars
# apply the agent's diff, commit, push, open PR
# CI runs: dbt build --select state:modified+  (Slim CI: only changed models and downstream)

Expected output: CI builds the changed models and runs their tests against the warehouse. Green CI means the change is at least structurally sound and data-valid per the project's own tests.

1. Require the agent to explain test failures and propose fixes, still as diffs:

AGENT: the not_null test on order_id failed with 3 violations.
CAUSE: the new join to refunds fans out on multi-refund orders.
FIX: (diff) pre-aggregate refunds per order before joining.

Expected output: a diagnosis tied to the failing test and a new diff. The loop continues until CI is green; the agent never merges red.

1. After merge, have the agent confirm downstream health:

dbt build --select +marts.orders+   # the model and everything downstream
# check: exposures and dashboards that consume it still pass their freshness checks

Expected output: confirmation that downstream models and exposures are healthy after the merge. The handoff is not done at merge; it is done when downstream is verified.

Variant phrasings

AI agent dbt workflow

The workflow is read artifacts, propose diff, PR, CI gate, human merge, verify downstream. Every step has a clear owner.

LLM propose dbt model changes

Proposing is the agent's job; deciding is CI's and the human's job. The diff format keeps those roles separate.

agent assisted dbt development

Assistance shines on boilerplate, staging models, test coverage, and refactors. Judgment calls on grain and business logic stay human.

Why it happens

dbt projects already solved the hard parts of collaborative data work: version control, dependency graphs, testing, and CI. The handoff pattern plugs the agent into that existing machinery instead of inventing a parallel one. Direct agent writes bypass all of it, which is how you get untested models in production with no record of who decided what. The diff-plus-PR shape also matches how agents are already good at working: produce a concrete proposal, let deterministic systems verify it.

Edge cases

• Complex macros confuse agents; point the agent at the macro's compiled SQL in the manifest rather than the Jinja source.
• Slim CI needs a comparison artifact (a prior manifest); without it, CI builds everything and the feedback loop gets slow.
• Style drift: agents write valid but unidiomatic SQL; run sqlfluff or your linter in CI so style is enforced, not debated.
• The agent may propose changes beyond the asked scope; the PR review is where scope gets trimmed, so keep PRs small.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2PqKu4knmEZqVtMF3PeUIg