Creating Agents

An agent is a YAML configuration file that defines when and how to automate a specific data engineering task. Agents respond to triggers like pull requests, schedules, or pipeline failures, and can take actions like creating PRs, posting comments, running SQL, and sending Slack notifications. This guide covers everything you need to create, configure, and deploy effective agents.

Getting Started

To create an agent, you need three core elements: a name, at least one trigger, and a prompt. The simplest agent looks like this:

my-agent.yml

name: my-first-agent

prompt: |
  Review this PR for dbt best practices.
  Comment if you find any issues.

triggers:
  - event: pull_request

Start with a single, specific task. You can always create additional agents for other workflows.

Enable Schema Validation

Add type safety and autocomplete to your agent files by including a JSON schema reference at the top of your YAML file:

agent.yaml

# yaml-language-server: $schema=https://platform.buster.so/schemas/v1/custom-agent.schema.json

name: my-first-agent
triggers:
  - event: pull_request
prompt: |
  Review this PR for dbt best practices.
  Comment if you find any issues.

VS Code users: You MUST have the YAML extension by Red Hat installed for schema validation and autocomplete to work.

This schema reference (platform.buster.so/schemas/v1/custom-agent.schema.json) enables type safety and real-time validation in your IDE, providing autocomplete suggestions and helping you catch configuration errors before deployment.

Project Setup

Agents are referenced from your buster.yml configuration file:

buster.yml

projects:
  - name: analytics
    data_source: my_datasource
    schema: public

agents:
  - .buster/agents/my-agent.yml

Then deploy with:

buster deploy

Reference

Core Fields

name

string

required

Unique identifier for your agent. Used in logs, the web interface, and GitHub Check Runs.Example: documentation_agent, pr-reviewer

description

string

A brief explanation of what the agent does. Appears in the web interface and helps team members understand the agent’s purpose.Example: Automatically maintains dbt model documentation

prompt

string

required

Instructions for the agent in natural language. Write this like you’re instructing a colleague—be clear about goals but let the agent determine implementation details.The agent has access to:

Your repository files (read, write, edit)
Your data warehouse (run SQL queries, retrieve metadata)
dbt project context (if configured)
Git operations (commits, branches, PRs via bash/gh commands)
Slack (if slack_tool is enabled)

Structure your prompt with clear steps when you want a specific workflow. Use open-ended instructions when you want the agent to figure out the best approach.

triggers

array

required

Defines when the agent runs. You must specify at least one trigger. See Triggers & Scheduling for complete details.

triggers:
  - event: pull_request
    types: ['opened', 'synchronize']
    branches: ['main']
    includes:
      - "models/**/*.sql"

tools

object

Configure additional tools for the agent.

Show Tools configuration

include

array

List of additional tools to enable. Currently, only slack_tool is available as an opt-in tool.

tools:
  include:
    - slack_tool

All other tools (file operations, SQL, bash, etc.) are available by default.

Triggers

Agents support four trigger types:

Event	Description
`pull_request`	Runs when PRs are opened or updated
`push`	Runs when commits are pushed to branches
`scheduled`	Runs on a cron schedule
`airflow`	Runs when Airflow pipelines fail

Pull Request Trigger

triggers:
  - event: pull_request
    branches: ['main', 'develop']
    types: ['opened', 'synchronize', 'reopened']
    includes:
      - "models/**/*.sql"
      - "models/**/*.yml"
    auto_commit: false

event

"pull_request"

required

Trigger type for pull request events.

branches

array

Branch patterns to match. Defaults to ["*"] (all branches).

types

array

PR event types that trigger the agent:

opened — PR was created
synchronize — New commits pushed to PR
reopened — PR was reopened after being closed

includes

array

Glob patterns for file filtering. Only triggers if at least one changed file matches.

includes:
  - "models/**"
  - "schemas/**/*.yml"

auto_commit

boolean

Controls how the agent commits changes:

false (default) — Creates a new branch from the PR’s head and opens a new PR with changes. Safe for collaboration.
true — Commits directly to the PR’s branch. Can cause conflicts if others are also pushing.

Use auto_commit: true with caution. It can cause merge conflicts if multiple people are working on the same PR.

Push Trigger

triggers:
  - event: push
    branches: ['main']
    includes:
      - "**/*.sql"

Fires when commits are pushed directly to a branch.

Scheduled Trigger

triggers:
  - event: scheduled
    cron: "0 9 * * 1"  # Every Monday at 9 AM UTC
    branches: ['main']
    includes:
      - "models/**"

cron

string

required

Cron expression (5 fields): minute hour day month weekdayCommon patterns:

0 * * * * — Every hour
0 9 * * * — Daily at 9 AM UTC
0 9 * * 1 — Every Monday at 9 AM UTC
*/15 * * * * — Every 15 minutes

All schedules use UTC timezone. The agent only runs if files matching includes have changed since the last run.

Airflow Trigger

triggers:
  - event: airflow
    type: dag_run_failed
    includes:
      - "critical_pipeline"
      - "data_quality_dag"

type

string

required

Airflow event type:

dag_run_failed — DAG run failed
task_instance_failed — Individual task failed

includes

array

Specific DAGs or tasks to filter. Only triggers for matching DAG/task names.

Available Tools

Agents have access to these tools by default:

Tool	Description
`Read`	Read file contents
`Write`	Create or overwrite files
`Edit`	Edit existing files with search-and-replace
`Bash`	Execute shell commands (git, dbt, python, etc.)
`Grep`	Search file contents
`Glob`	Find files by pattern
`LS`	List directory contents
`RunSql`	Execute SQL queries against your data warehouse
`RetrieveMetadata`	Get column statistics, distributions, and cardinality

Optional Tools

Enable additional tools with tools.include:

Tool	Description
`slack_tool`	Send messages to Slack channels

tools:
  include:
    - slack_tool

Git Operations

Agents perform Git operations through the Bash tool using git and gh (GitHub CLI) commands:

prompt: |
  After making changes:
  1. Create a new branch: git checkout -b agent/docs-update
  2. Commit changes: git add . && git commit -m "docs: Update model documentation"
  3. Push and create PR: gh pr create --title "Documentation update" --body "Auto-generated by Buster"

Examples

Documentation Updater
PR Reviewer
Scheduled Audit
Airflow Failure Handler

documentation-agent.yml

name: documentation_agent
description: Automatically updates dbt model documentation

prompt: |
  When triggered by a pull request:
  
  1. Identify all changed SQL model files
  2. For each changed model:
     - Use RetrieveMetadata to get column statistics
     - Update the corresponding YAML file with:
       - Model description (purpose, grain, approximate row count)
       - Column descriptions with data types and null rates
  3. Run `dbt parse` to validate changes
  4. If valid, commit changes and post a summary comment
  5. If invalid, post the error as a PR comment

triggers:
  - event: pull_request
    branches: ['main', 'develop']
    types: ['opened', 'synchronize']
    includes:
      - "models/**/*.sql"
    auto_commit: false

tools:
  include:
    - slack_tool

pr-reviewer.yml

name: pr_reviewer
description: Reviews dbt PRs for best practices

prompt: |
  Review this pull request for dbt best practices.
  
  Check for:
  - Models missing documentation
  - SQL anti-patterns (SELECT *, inconsistent naming)
  - Missing tests on key columns
  - Changes that might break downstream dependencies
  
  Post your findings as a PR comment. Be constructive and helpful.
  If everything looks good, leave a positive comment.

triggers:
  - event: pull_request
    types: ['opened', 'synchronize']
    includes:
      - "models/**"
      - "macros/**"

weekly-audit.yml

name: weekly_audit
description: Weekly documentation coverage audit

prompt: |
  Audit documentation coverage for all models in models/marts/.
  
  For each model, check:
  1. Does it have a description?
  2. Does each column have a description?
  3. Does it have at least one test?
  
  Generate a report with:
  - Overall coverage percentage
  - Models needing attention (sorted by priority)
  - Suggestions for improvement
  
  Send the report to #data-documentation on Slack.

triggers:
  - event: scheduled
    cron: "0 9 * * 1"  # Every Monday at 9 AM UTC
    branches: ['main']

tools:
  include:
    - slack_tool

airflow-handler.yml

name: airflow_failure_handler
description: Investigates Airflow pipeline failures

prompt: |
  An Airflow DAG has failed. Investigate the failure:
  
  1. Check the error message provided in the trigger context
  2. Look for related models in the repository
  3. Query recent data to identify potential issues
  4. Create a GitHub issue with:
     - Summary of the failure
     - Potential root causes
     - Suggested investigation steps
  5. Send an alert to #data-incidents on Slack

triggers:
  - event: airflow
    type: dag_run_failed
    includes:
      - "critical_pipeline"
      - "daily_refresh"

tools:
  include:
    - slack_tool

Best Practices

Writing Effective Prompts

Be specific about the desired outcome

Instead of “check for issues,” specify what issues to look for and what to do when found.

# Vague
prompt: Check this PR

# Specific
prompt: |
  Check if new columns in staging models follow our naming convention:
  - Boolean columns must start with "is_" or "has_"
  - Date columns must end with "_date" or "_at"
  - Amount columns must end with "_amount" or "_value"
  
  If violations found, comment on the PR with specific file and line numbers.

Structure complex prompts with numbered steps

For multi-step workflows, use numbered lists to clarify sequence and dependencies.

prompt: |
First, identify all changed models in this PR
For each model, use RetrieveMetadata to get column stats
Update YAML documentation based on the metadata
Run dbt parse to validate syntax
If validation passes, commit changes
Post a summary comment listing what was updated

Specify the output format

Tell the agent how to present results—should it create a PR, post a comment, send a Slack message?

prompt: |
  Generate a documentation coverage report.
  
  Format the report as a Slack message with:
  - Summary statistics at the top
  - Emoji indicators (✅ good, ⚠️ warning, ❌ critical)
  - Bulleted list of models needing attention
  
  Send to #data-documentation channel.

Handle error cases

Define what the agent should do when things go wrong.

prompt: |
  Update documentation for changed models.
  
  If dbt parse fails:
  - Do NOT commit the changes
  - Post the error message as a PR comment
  - Tag @data-platform-team for review
  
  If unable to connect to the warehouse:
  - Post a comment explaining the issue
  - Do not block the PR

Choosing the Right Trigger

Match your trigger to the workflow pattern:

pull_request — Code review, validation, documentation updates
push — Post-merge automation, deployment triggers
scheduled — Regular audits, monitoring, batch processing
airflow — Pipeline failure response

Testing Agents

Before deploying to production:

Validate configuration:
```
buster deploy --dry-run --verbose
```
Test with a sample PR: Create a test branch and open a PR to see how the agent behaves.
Monitor initial runs: Check the Runs tab in the web app to see execution logs and outputs.
Iterate on the prompt: Refine based on actual behavior—add specificity where the agent made unexpected decisions.

Deployment

After creating your agent:

Reference it in buster.yml:

agents:
  - .buster/agents/my-agent.yml

Deploy:
```
buster deploy
```
Verify: Check the Buster web app to confirm your agent appears in the list.

The agent will start responding to its configured triggers immediately after deployment.

Every agent execution creates a GitHub Check Run and is logged in the Buster web app for full transparency and debugging.

Introduction

Guides

Examples

Resources

Creating Agents

Getting Started

Enable Schema Validation

Project Setup

Reference

Core Fields

Triggers

Pull Request Trigger

Push Trigger

Scheduled Trigger

Airflow Trigger

Available Tools

Optional Tools

Git Operations

Examples

Best Practices

Writing Effective Prompts

Choosing the Right Trigger

Testing Agents

Deployment

Introduction

Guides

Examples

Resources

​Getting Started

​Enable Schema Validation

​Project Setup

​Reference

​Core Fields

​Triggers

​Pull Request Trigger

​Push Trigger

​Scheduled Trigger

​Airflow Trigger

​Available Tools

​Optional Tools

​Git Operations

​Examples

​Best Practices

​Writing Effective Prompts

​Choosing the Right Trigger

​Testing Agents

​Deployment

Getting Started

Enable Schema Validation

Project Setup

Reference

Core Fields

Triggers

Pull Request Trigger

Push Trigger

Scheduled Trigger

Airflow Trigger

Available Tools

Optional Tools

Git Operations

Examples

Best Practices

Writing Effective Prompts

Choosing the Right Trigger

Testing Agents

Deployment