Complete reference for agent configuration files.
File Location Agent files are YAML files referenced from your buster.yml:
agents : - .buster/agents/my-agent.yml - .buster/agents/another-agent.yml We recommend storing agents in .buster/agents/.
Complete Schema name : string # Required: Unique agent identifier description : string # Optional: Description shown in UI prompt : | # Required: Instructions for the agent Multi-line prompt text that instructs the agent what to do. triggers : # Required: At least one trigger - event : string # Required: pull_request, push, scheduled, airflow # ... trigger-specific fields tools : # Optional: Additional tools include : - slack_tool # Currently the only opt-in tool Fields name Unique identifier for the agent. Used in logs, the web interface, and GitHub Check Runs. name : documentation_agent description Brief explanation of what the agent does. Appears in the web interface. description : Automatically maintains dbt model documentation prompt Instructions for the agent in natural language. Write this like you’re instructing a colleague. prompt : | When triggered by a pull request: 1. Identify changed SQL model files 2. Profile each model using RetrieveMetadata 3. Update YAML documentation 4. Commit changes if valid The agent has access to:
Your repository files (read, write, edit)
Your data warehouse (SQL queries, metadata)
Git operations (via bash)
Slack (if slack_tool enabled)
triggers Defines when the agent runs. At least one trigger is required. See Trigger Reference below for complete details. triggers : - event : pull_request types : [ 'opened' , 'synchronize' ] includes : - "models/**/*.sql" Configure additional tools for the agent. tools : include : - slack_tool List of additional tools to enable. Currently only slack_tool is available. All other tools (file operations, SQL, bash) are available by default.
Triggers Reference Pull Request Trigger Runs when pull request events occur.
triggers : - event : pull_request repository : owner/repo # Optional: defaults to current repo branches : # Optional: defaults to ["*"] - main - develop types : # Optional: PR event types - opened - synchronize - reopened includes : # Optional: file patterns to match - "models/**/*.sql" auto_commit : false # Optional: defaults to false Repository in owner/repo format. Defaults to current repository.
Branch patterns the PR must target. Defaults to ["*"] (all branches).
PR event types that activate the trigger: Type Description openedPR was created synchronizeNew commits pushed to PR reopenedPR was reopened
Glob patterns for file filtering. Only triggers if changed files match.
How the agent commits changes: Value Behavior false (default)Creates new branch and opens new PR trueCommits directly to PR branch
Push Trigger Runs when commits are pushed to a branch.
triggers : - event : push repository : owner/repo # Optional branches : # Optional: defaults to ["*"] - main includes : # Optional: file patterns - "**/*.sql" Repository in owner/repo format. Defaults to current repository.
Branches to watch. Defaults to ["*"] (all branches).
Glob patterns for file filtering.
Scheduled Trigger Runs on a cron schedule.
triggers : - event : scheduled cron : "0 9 * * 1" # Required: cron expression repository : owner/repo # Optional branches : # Optional: defaults to ["*"] - main includes : # Optional: only runs if these changed - "models/**" Cron expression (5 fields): minute hour day month weekday Expression Description 0 * * * *Every hour 0 9 * * *Daily at 9 AM UTC 0 9 * * 1Every Monday at 9 AM UTC */15 * * * *Every 15 minutes
Branches to check for changes.
File patterns. Agent only runs if matching files changed since last run.
Airflow Trigger Runs when Airflow pipelines fail.
triggers : - event : airflow type : dag_run_failed # Required: event type repository : owner/repo # Optional includes : # Optional: DAG/task names to filter - "critical_pipeline" Airflow event type: Type Description dag_run_failedDAG run failed task_instance_failedTask failed
DAG or task names to filter. Only triggers for matching names.
Tool Description ReadRead file contents WriteCreate or overwrite files EditEdit files with search-and-replace BashExecute shell commands GrepSearch file contents GlobFind files by pattern LSList directory contents RunSqlExecute SQL queries RetrieveMetadataGet column statistics and distributions
Tool How to Enable slack_tooltools.include: [slack_tool]
Examples Minimal Agent name : my_agent prompt : Review this PR for issues. triggers : - event : pull_request Documentation Agent name : documentation_agent description : Updates model documentation on PRs prompt : | For each changed SQL model: 1. Use RetrieveMetadata to profile columns 2. Update YAML documentation 3. Run dbt parse to validate 4. Commit changes triggers : - event : pull_request types : [ 'opened' , 'synchronize' ] includes : - "models/**/*.sql" auto_commit : false Scheduled Audit with Slack name : weekly_audit description : Weekly documentation coverage audit prompt : | Audit documentation coverage for all models. Send report to #data-team on Slack. triggers : - event : scheduled cron : "0 9 * * 1" branches : [ 'main' ] tools : include : - slack_tool Multi-Trigger Agent name : docs_maintainer prompt : | Maintain documentation for dbt models. triggers : - event : pull_request types : [ 'opened' , 'synchronize' ] includes : [ "models/**/*.sql" ] - event : scheduled cron : "0 9 * * 1" branches : [ 'main' ] - event : push branches : [ 'main' ] includes : [ "models/**/*.sql" ] 
