Использование субагентов в dbt Wizard CLI Бета-версия
Субагенты позволяют dbt Wizard запускать специализированных агентов, которые параллельно выполняют части более крупной задачи — один исследует ваш проект, другой вносит изменения, третий проверяет их. dbt Wizard координирует их работу и объединяет результаты в вашем сеансе.
Используйте субагентов, когда задачу можно разделить на независимые части. Они полезны для проверки большого pull request, отладки задания, завершившегося с ошибкой, добавления тестов для нескольких моделей или поиска информации в документации, пока другой агент изучает ваш проект.
Для небольших, конкретных задач субагенты обычно не нужны. Задайте один вопрос, например «Что делает эта модель?» или «Исправь этот тест, который завершается с ошибкой», не распределяя работу между агентами.
Субагенты выполняют работу параллельно, что расходует больше токенов, чем выполнение той же задачи в сеансе с одним агентом. Используйте их, когда разделение работы помогает решить задачу.
Хотите увидеть dbt Wizard в действии? Посмотрите демонстрационное видео.
Нам было бы интересно узнать о вашем опыте работы с dbt Wizard. Поделитесь отзывом, выполнив слеш-команду /feedback в интерактивном сеансе терминала или перейдя в канал #dbt-wizard в Slack-сообществе dbt.
Большое спасибо за помощь в улучшении dbt Wizard и процесса разработки данных с помощью dbt!
Расположение и приоритет
Вы можете определять собственные роли агентов, добавляя отдельные TOML-файлы на уровне проекта или пользователя. Используйте агентов уровня проекта для ролей, которые должны распространяться вместе с репозиторием, а агентов уровня пользователя — для ролей, которые нужны во всех локальных проектах.
В следующей таблице перечислены расположения, в которых dbt Wizard ищет пользовательских агентов. Для новых агентов используйте предназначенные для этого расположения, а расположения для совместимости сохраняйте только при переносе существующей конфигурации. Конфигурация агентов уровня проекта загружается только для доверенных проектов. Среди расположений уровня проекта текущий рабочий каталог имеет приоритет над родительскими каталогами. Агенты уровня проекта имеют приоритет над агентами уровня пользователя с тем же именем.
| Расположение | Уровень | Использовать для новых агентов? | Приоритет |
|---|---|---|---|
.dbt/wizard/agents/NAME.toml | Проект | Да. Используйте для агентов, общих для репозитория или подкаталога. | Наивысший приоритет среди расположений агентов проекта; расположения ближе к текущему рабочему каталогу имеют приоритет над родительскими каталогами. |
~/.dbt/wizard/agents/NAME.toml | Пользователь | Да. Используйте для агентов, которые нужны во всех локальных проектах. | Ниже агентов проекта, выше импортов для совместимости. |
.claude/agents/NAME.md | Проект | Нет. Импорт существующих агентов Claude Code для совместимости. | Ниже .dbt/wizard/agents/ в том же расположении проекта. |
~/.claude/agents/NAME.md | Пользователь | Нет. Импорт существующих агентов Claude Code для совместимости. | Ниже ~/.dbt/wizard/agents/. |
Если два пользовательских агента имеют одинаковое имя, dbt Wizard использует расположение с более высоким приоритетом и по возможности заполняет отсутствующие поля из расположений с более низким приоритетом. Избегайте повторяющихся имён, если только вы не хотите намеренно переопределить существующую роль.
Где можно использовать субагентов
Субагенты работают в dbt Wizard CLI.
Вы можете определять собственные роли агентов, задавать отображаемые псевдонимы и настраивать глобальные ограничения в файле config.toml.
Как работают субагенты
Агент — это роль, описывающая тип работы, например explorer, worker или test_writer.
Субагент — это запущенный экземпляр одной из таких ролей. Например, если вы запускаете двух агентов explorer для ответа на два разных вопроса, у вас будет два субагента с одной и той же ролью.
dbt Wizard берёт на себя координацию. Он запускает субагентов, направляет им работу, ожидает результатов и объединяет их вывод в вашем сеансе.
Вы можете использовать субагентов следующими способами:
| Как запускаются субагенты | Пример |
|---|---|
| Вы просите разделить работу. | Review PR #123. Use one agent to map what changed, one to check tests and downstream impact, and one to look up the relevant dbt docs. |
| dbt Wizard автоматически использует настроенного агента, поскольку ваша задача соответствует его описанию. | Add tests for stg_customers and check whether similar staging models are missing tests. |
Затем dbt Wizard запускает агентов, позволяет им работать параллельно и объединяет их выводы в одном ответе.
Встроенные агенты
В dbt Wizard есть встроенные агенты, которых можно запускать без настройки. Некоторые из них специально предназначены для работы с dbt:
| Агент | Для чего предназначен | Пример |
|---|---|---|
explorer | Отвечает на конкретные, чётко ограниченные вопросы о вашем проекте. Работает быстро и только в режиме чтения — запускайте несколько экземпляров параллельно для независимых вопросов. | Use explorer to explain what depends on fct_orders. |
worker | Выполняет практические задачи, например реализует часть функциональности, исправляет тесты или ошибки либо разбивает масштабный рефакторинг на независимые части. | Use worker to update these staging models to follow our naming convention. |
validation | Выполняет проверку dbt. После редактирования моделей проводит структурированную проверку — проверку SQL, dbt run с --defer, сравнение prod и dev и анализ влияния — чтобы проверить изменения перед слиянием. | Use validation to check whether my changes to int_payments are safe to merge. |
test_writer | Улучшает покрытие тестами dbt. Анализирует метаданные проекта и данные в хранилище, чтобы найти пробелы в покрытии, проверяет предположения с помощью запросов и пишет тесты в schema.yml для моделей с низким покрытием или без него. | Use test_writer to add tests to stg_customers. |
Объявлять этих агентов не нужно — dbt Wizard автоматически направляет им подходящие задачи, или вы можете запросить агента по имени. Например, оба этих запроса могут задействовать агента test_writer:
| Стиль запроса | Пример |
|---|---|
| Запрос на естественном языке | Добавь полезные тесты для stg_customers. |
| Запрос агента по имени | Используй test_writer, чтобы добавить тесты для stg_customers. |
Чтобы добавить собственные роли, обратитесь к разделу Пользовательские агенты.
Управление субагентами
Используйте слеш-команды в интерактивном сеансе, чтобы просматривать потоки агентов и направлять их работу:
| Команда | Что делает | Пример |
|---|---|---|
/agent | Переключает активный поток агента, чтобы просмотреть текущую работу или направить её. | Используйте /agent, когда хотите перейти из основного сеанса в поток конкретного агента и дать ему дополнительные указания. |
/subagents | Показывает запущенные потоки субагентов и позволяет переключаться между ними. | Используйте /subagents, чтобы увидеть, какие вспомогательные агенты активны при выполнении делегированной задачи, а затем выберите одного из них, чтобы просмотреть ход его работы. |
Вы также можете на естественном языке попросить dbt Wizard направить работу потока агента, остановить или закрыть его. Например: Stop the docs researcher agent and continue with the reviewer findings.
Полный список команд сеанса приведён в справочнике слеш-команд.
Подтверждения и песочница
Субагенты наследуют политику подтверждений и песочницы родительского сеанса. Любые переопределения, которые вы задаёте на время выполнения одного хода (разрешения, режим песочницы), применяются к запускаемым в этом ходе субагентам. Когда субагент запрашивает подтверждение, в вашем сеансе отображается запрос с указанием источника, чтобы вы знали, какой агент его отправил.
Пользовательский агент может переопределить для себя настройки песочницы — это полезно, например, когда агенту для исследования нужен только доступ на чтение, а агенту для сборки требуется доступ на запись в рабочую область.
Пользовательские агенты
Роль пользовательского агента — это многократно используемая роль для определённого типа работы, которую вы хотите поручить dbt Wizard, например написания UDF, исследования проекта или отладки проблемы. Вы можете выбрать любое имя роли, подходящее для вашего рабочего процесса; оно не обязано совпадать с одной из встроенных ролей.
Каждый файл определяет одну роль пользовательского агента. Имя файла должно совпадать со значением поля name агента. Например, агент с name = "udf_helper" должен быть определён в файле agents/udf_helper.toml.
dbt Wizard загружает каждый файл пользовательского агента как слой конфигурации для запускаемых сеансов агентов. Это означает, что пользовательский агент может переопределять те же настройки, что и обычная конфигурация сеанса dbt Wizard, например модель, инструкции, режим песочницы и MCP-серверы.
Лучшие пользовательские агенты имеют узкую специализацию и чётко заданный подход к работе. Дайте каждому конкретную задачу, необходимые для неё инструменты и инструкции, которые не позволят ему отвлекаться на смежную работу.
Каждый файл пользовательского агента должен определять:
| Поле | Обязательное | Описание |
|---|---|---|
name | Да | Имя агента, которое dbt Wizard использует при его запуске или обращении к нему. Должно совпадать с именем файла без .toml. Например, name = "udf_helper" должно находиться в udf_helper.toml. |
description | Да | Объясняет, когда следует использовать агента. dbt Wizard читает это описание, чтобы определить, подходит ли агент для задачи. |
developer_instructions | Да | Инструкции для самостоятельно размещённого dbt, определяющие поведение агента. |
nickname_candidates | Нет | Метки, используемые только для отображения запущенных экземпляров этого агента в интерфейсе, например UDF helper или UDF queen. Псевдоним не служит идентификатором агента. |
model | Нет | Модель, которую должен использовать этот агент. Если не указана, наследуется из родительского сеанса. |
sandbox_mode | Нет | Режим песочницы для этого агента. Если не указан, наследуется из родительского сеанса. |
mcp_servers | Нет | MCP-серверы, доступные этому агенту. Если не указаны, наследуются из родительского сеанса. |
В файл пользовательского агента также можно включать другие поддерживаемые ключи config.toml. Любая настройка, не заданная в файле пользовательского агента, наследуется из родительского сеанса.
Пример пользовательского агента
Создайте отдельный файл пользовательского агента. Имя файла и значение name должны совпадать:
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"]
Затем попросите dbt Wizard использовать агента по имени:
Use udf_helper to create a UDF model that checks whether customer IDs are positive integers.
Вы также можете позволить dbt Wizard выбрать агента автоматически, описав задачу:
Create a dbt UDF that checks whether customer IDs are positive integers, then add a small model that uses it.
Отображаемые псевдонимы
Когда одновременно работают несколько экземпляров одного агента, используйте nickname_candidates, чтобы дать каждому экземпляру понятную метку в интерфейсе. Например, два запущенных агента udf_helper могут отображаться как UDF helper и UDF queen.
Псевдонимы используются только для отображения. dbt Wizard определяет агента по полю name, а не по псевдониму, показанному в интерфейсе.
Пример с MCP-сервером
Файлы пользовательских агентов могут содержать конфигурацию MCP-сервера, если агенту нужны дополнительные инструменты или контекст.
Как и прежде, имя файла и значение name должны совпадать:
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"]
Эта конфигурация хорошо подходит для таких запросов:
Have udf_helper design the UDF change and dbt_docs_helper verify the dbt function configuration.
Глобальные настройки
Глобальные настройки субагентов находятся в секции [agents] файла ~/.dbt/wizard/config.toml:
[agents]
max_depth = 2
job_max_runtime_seconds = 1800
interrupt_message = true
| Ключ | Описание |
|---|---|
max_depth | Максимальная глубина вложенности запускаемых потоков агентов. Корневые сеансы начинаются с глубины 0. |
job_max_runtime_seconds | Максимальное время выполнения по умолчанию, в секундах, для агентов, выполняющих задания. |
interrupt_message | Определяет, нужно ли записывать видимое модели сообщение при прерывании хода агента. По умолчанию — true. |
Примеры
Реализация UDF
Определите пользовательского агента, специализирующегося на работе с UDF в dbt. Каждый пользовательский агент — это отдельный TOML-файл в ~/.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"]
При необходимости задайте глобальные настройки субагентов в основном файле config.toml:
[agents]
max_depth = 2
Затем отправьте запрос 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 запускает указанного агента, позволяет ему реализовать UDF и добавляет итоговый результат в ваш сеанс.
Отладка запуска задания, завершившегося с ошибкой (главное приложение)
В главном приложении dbt platform попросите dbt Wizard исследовать задание, завершившееся с ошибкой, делегировав работу специализированным агентам:
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 запускает агентов, каждый из них работает над своей частью подключённого проекта, а dbt Wizard объединяет результаты диагностики и предложенное исправление в одном ответе.
Связанная документация
- Использование MCP-серверов с dbt Wizard CLI — чтобы предоставить агентам дополнительные инструменты и контекст
- Использование навыков — для многократно используемых инструкций, специфичных для проекта
- Слеш-команды dbt Wizard — о командах
/agentи/subagents - Конфигурация dbt Wizard CLI — о ключах
config.tomlи приоритетах - Как работает dbt Wizard — о подтверждениях и песочнице
