Use subagents with dbt Wizard Beta
Subagents let dbt Wizard spin up focused, parallel agents to handle parts of a larger task — one to explore your project, one to make changes, one to review them. dbt Wizard orchestrates them and consolidates the results back into your session.
Use subagents when you can split a task into independent pieces of work. They're useful for reviewing a large pull request, debugging a failed job, adding tests across multiple models, or researching documentation while another agent inspects your project.
For smaller, direct tasks, you usually don't need subagents. Ask a single question, like "What does this model do?" or "Fix this failing test," without splitting the work across agents.
Subagents run work in parallel, which uses more tokens than handling the same task in a single-agent session. Use them when the task benefits from dividing the work.
We'd love to hear how dbt Wizard is working for you. Share your feedback by either running the /feedback slash command in your interactive terminal session or by going to the #dbt-wizard channel in the dbt Community Slack.
Thanks so much for your help in improving dbt Wizard and dbt data development!
Where you can use subagents
Subagents work in dbt Wizard both in the dbt platform (Studio IDE and the home app) and in the dbt Wizard CLI.
dbt Wizard surfaces subagent activity in both places so you can see what each agent is working on.
In the CLI, you can also define custom agent roles, set display nicknames, and configure global limits through the config.toml file. The following sections call out which steps are CLI-specific.
How subagents work
An agent is a role that describes a type of work, like explorer, worker, or test_writer.
A subagent is a running instance of one of those roles. For example, if you start two explorer agents to answer two different questions, you have two subagents that share the same agent role.
dbt Wizard handles orchestration for you. It starts subagents, routes work to them, waits for their results, and consolidates their output into your session.
You can use subagents in the following ways:
| Loading table... |
dbt Wizard then spawns the agents, lets them work in parallel, and brings their findings back into one response.
Built-in agents
dbt Wizard ships with built-in agents that it can spawn without any configuration. Several are purpose-built for dbt work:
You don't need to declare these — dbt Wizard routes to them automatically when a task fits, or you can ask for one by name. For example, both of these prompts can use the test_writer agent:
| Loading table... |
To add your own roles, refer to Custom agents.
Manage subagents
Use slash commands inside an interactive session to inspect and steer agent threads:
You can also tell dbt Wizard in plain language to steer, stop, or close an agent thread. For example, Stop the docs researcher agent and continue with the reviewer findings.
For the full list of session commands, refer to the slash command reference.
Approvals and sandbox
Subagents inherit the parent session's approval and sandbox policy. Any runtime overrides you set for a turn (permissions, sandbox mode) apply to the subagents it spawns. When a subagent requests approval, your session shows the request with its source so you know which agent is asking.
A custom agent can override sandbox settings for itself — useful when, for example, an exploration agent should stay read-only while a build agent needs workspace write access.
Custom agents (CLI)
You can define custom agent roles by adding standalone TOML files under ~/.dbt/wizard/agents/.
A custom agent role is a reusable role for a particular type of work you want dbt Wizard to perform, such as writing UDFs, exploring a project, or debugging an issue. You can create any role name that fits your workflow; it does not have to be one of the built-in roles.
Each file defines one custom agent role. The file name must match the agent's name field. For example, an agent with name = "udf_helper" must be defined in ~/.dbt/wizard/agents/udf_helper.toml.
dbt Wizard loads each custom agent file as a configuration layer for spawned agent sessions. This means a custom agent can override the same settings as a normal dbt Wizard session config, such as the model, instructions, sandbox mode, and MCP servers.
The best custom agents are narrow and opinionated. Give each one a clear job, the tools it needs for that job, and instructions that keep it from drifting into adjacent work.
Every custom agent file must define:
You can also include other supported config.toml keys in a custom agent file. Any setting you don't define in the custom agent file inherits from the parent session.
Example custom agent
Create a standalone custom agent file. The file name and name value must match:
name = "udf_helper" # matches the udf_helper.toml file name
description = "Helps design and implement dbt UDFs and models that use them."
developer_instructions = """
You are an expert in dbt UDFs.
Focus on:
- choosing the right UDF pattern
- writing clear function definitions
- configuring function paths
- using {{ function() }} references correctly
- adding focused models and tests that demonstrate the UDF
- keeping changes small and additive
Before editing files, explain the proposed UDF design.
When editing files, avoid unrelated changes.
"""
sandbox_mode = "workspace-write"
nickname_candidates = ["UDF helper", "UDF queen"]
Then ask dbt Wizard to use the agent by name:
Use udf_helper to create a UDF model that checks whether customer IDs are positive integers.
You can also let dbt Wizard choose the agent automatically by describing the task:
Create a dbt UDF that checks whether customer IDs are positive integers, then add a small model that uses it.
Display nicknames
When several instances of the same agent run at once, use nickname_candidates to give each instance a readable label in the UI. For example, two spawned udf_helper agents might appear as UDF helper and UDF queen.
Nicknames are display-only. dbt Wizard identifies the agent by its name field, not by the nickname shown in the UI.
Example with an MCP server
Custom agent files can include MCP server configuration when the agent needs additional tools or context.
Again, the file name and name value must match:
name = "dbt_docs_helper"
description = "Looks up relevant dbt documentation for patterns referenced in a change."
developer_instructions = """
Use the dbt docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not edit files.
"""
sandbox_mode = "read-only"
[mcp_servers.dbt]
command = "uvx"
args = ["dbt-mcp"]
This setup works well for prompts like:
Have udf_helper design the UDF change and dbt_docs_helper verify the dbt function configuration.
Global settings
Global subagent settings live under the [agents] section in ~/.dbt/wizard/config.toml:
[agents]
max_depth = 2
job_max_runtime_seconds = 1800
interrupt_message = true
Examples
UDF implementation
Define a custom agent that specializes in dbt UDF work. Each custom agent is a standalone TOML file under ~/.dbt/wizard/agents/.
name = "udf_helper"
description = "Helps design and implement dbt UDFs and models that use them."
developer_instructions = """
You are an expert in dbt UDFs.
Focus on:
- choosing the right UDF pattern
- writing clear function definitions
- configuring function paths
- using {{ function() }} references correctly
- adding focused models and tests that demonstrate the UDF
- keeping changes small and additive
Before editing files, explain the proposed UDF design.
When editing files, avoid unrelated changes.
"""
sandbox_mode = "workspace-write"
nickname_candidates = ["UDF helper", "UDF queen"]
Optionally, configure global subagent settings in your main config.toml:
[agents]
max_depth = 2
Then prompt dbt Wizard:
Use udf_helper to create a UDF that checks whether customer IDs are positive integers, then add a small model that uses it.
dbt Wizard starts the requested agent, lets it work on the UDF implementation, and consolidates the result into your session.
Debug a failed job run (home app)
In the dbt platform home app, ask dbt Wizard to investigate a failed job by delegating to focused agents:
The nightly job failed. Use one agent to pull the run error and logs,
one to trace the failing model's lineage and find the root cause, and
one to propose a fix. Summarize what each found.
dbt Wizard spawns the agents, each one works on its part of your connected project, and dbt Wizard consolidates the diagnosis and proposed fix into one response.
Related docs
- Use MCP servers with the dbt Wizard CLI to give agents more tools and context
- Use skills for reusable, project-specific instructions
- dbt Wizard slash commands for
/agentand/subagents - dbt Wizard CLI config for
config.tomlkeys and precedence - How dbt Wizard works for approvals and sandboxing
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
