## 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.

```text
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:

```bash
# 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.

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

```diff
--- 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.

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

```bash
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.

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

```text
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.

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

```bash
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