Actions & Notifications

Agents don’t just analyze and observe—they take action. From creating pull requests and posting comments to sending Slack notifications and setting status checks, agents can perform a wide range of operations based on what they discover. This guide covers all available actions, notification strategies, and best practices for reliable automation.

How Actions Work

Agents determine which actions to take based on your prompt instructions and the tools available to them. You describe desired outcomes in natural language, and the agent selects and executes the appropriate tools to accomplish those goals.

Think of actions as the “then” in “if-then” logic. Your prompt defines the conditions and the corresponding actions.

Action Selection

Agents intelligently choose actions based on:

What they discover during execution
Conditions specified in your prompt
Available tools and permissions
Context from the trigger

prompt: |
  Review this PR for breaking changes.

  If breaking changes found:
    - Leave a detailed PR comment
    - Set status check to failure
    - Send Slack alert to #data-alerts

  If no breaking changes:
    - Set status check to success
    - Post brief confirmation comment

The agent evaluates the condition, determines the appropriate branch, and executes the specified actions.

Available Actions

Git Operations

Create Pull Requests

action

Agents can create new pull requests with commits, descriptions, labels, and reviewers.

prompt: |
  Update staging models to match schema changes.

  Create a PR with:
    - Title: "fix(staging): Adapt to Salesforce schema changes"
    - Description:
      - List of columns added/removed
      - Staging models updated
      - Potential downstream impacts
    - Labels: "automated", "schema-change"
    - Reviewers: @data-team

What the agent does:

Creates a new branch (following branch_prefix if configured)
Makes file modifications
Commits changes with descriptive message
Pushes to remote
Opens PR via GitHub API with specified details

Requires git_operations tool and can_create_pr: true permission.

Comment on Pull Requests

action

Post comments to the triggering PR or other PRs.

prompt: |
  If code quality issues found, leave a comment with:
    - Summary of issues by severity
    - Specific file and line numbers
    - Suggested fixes with code examples
    - Links to style guide sections

Comment formatting:

Supports full Markdown formatting
Can include code blocks, tables, lists
Supports collapsible sections
Can mention users or teams

Use structured formatting for readability. Group related issues and provide actionable feedback.

Push Commits

action

Commit and push changes to the current branch.

prompt: |
  Fix linting issues in changed files.

  Commit with message: "style: Auto-fix linting issues"
  Include list of files modified in commit body.

Commit details:

Agent uses configured git user
Commits include detailed messages
Can sign commits if configured

Direct commits to protected branches may be blocked by branch protection rules.

GitHub Status Checks

Set Status Checks

action

Set commit status checks that can block PR merging.

prompt: |
  Run compliance checks on mart models.

  If violations found:
    - Set status to "failure"
    - Context: "Compliance Check"
    - Description: "Found {count} violations. Review required."

  If no violations:
    - Set status to "success"
    - Context: "Compliance Check"
    - Description: "All compliance checks passed"

Status levels:

success - Check passed, allow merge
failure - Check failed, block merge (if required)
pending - Check in progress
error - Check encountered an error

Status checks integrate with branch protection rules to enforce quality gates.

Slack Notifications

Send Slack Messages

action

Send formatted messages to configured Slack channels.

prompt: |
  If data drift detected, send Slack message to #data-alerts:

  **Title:** 🚨 Data Drift Alert

  **Metric:** {{ metric_name }}
  **Expected Range:** {{ expected_min }} - {{ expected_max }}
  **Actual Value:** {{ actual_value }}
  **Deviation:** {{ deviation_percent }}%

  **Affected Models:**
  {{ models_list }}

  **Recommended Actions:**
  • Review recent data loads
  • Check for upstream schema changes
  • Validate business logic

  cc: @data-platform-team

Formatting options:

Bold, italic, code, and ~~strikethrough~~
Bulleted and numbered lists
Code blocks with syntax highlighting
Links and mentions
Emojis for visual emphasis

Structure notifications with clear sections: what happened, impact, and next steps.

Thread Responses

action

Reply to existing Slack threads for context continuity.

prompt: |
  This is a follow-up to yesterday's drift alert.

  Send a threaded response to the original message with:
    - Current status update
    - Whether issue is resolved
    - Any remaining actions needed

Useful for ongoing investigations or multi-day processes.

File Operations

Create Files

action

Generate new files in the repository.

prompt: |
  Create a daily audit report in .buster/reports/audit-{{ date }}.md with:
    - Models checked
    - Issues found
    - Recommendations

Common use cases:

Generated documentation
Audit reports
Configuration files
Data quality logs

Requires write_file tool and can_create_files: true permission.

Update Files

action

Modify existing files with search-and-replace operations.

prompt: |
  Update model YAML files with column descriptions.

  For each model:
    - Add missing column descriptions
    - Update stale descriptions
    - Preserve existing documentation

Capabilities:

Precise search-and-replace
Multi-line edits
Preserves formatting
Can edit multiple files in one operation

Delete Files

action

Remove files from the repository (with appropriate permissions).

prompt: |
  Clean up temporary files from .buster/temp/ older than 7 days.

Requires delete_file tool, can_delete_files: true, and path not in critical_files.

Email Notifications

Send Emails

action

Send email notifications to specified recipients.

notifications:
  email:
    to: ["[email protected]"]
    on_failure: true

prompt: |
  If critical issues found, send email with:
    - Issue summary
    - Affected systems
    - Required actions

Email details:

HTML formatting supported
Can include attachments
Configurable triggers (success/failure)

Action Patterns

Conditional Logic

Binary decisions

Simple if-else logic for two outcomes:

prompt: |
  Check for breaking changes.

  If breaking changes found:
    - Comment with details
    - Set status to failure
    - Send Slack alert

  If no breaking changes:
    - Set status to success
    - Post brief confirmation

Multi-branch conditionals

Handle multiple scenarios with different actions:

prompt: |
  Analyze schema changes.

  If new columns added:
    - Update staging models
    - Create PR
    - Notify #data-engineering

  If columns removed:
    - Do NOT update automatically (too risky)
    - Comment with impact analysis
    - Request manual review
    - Notify #data-leads

  If columns renamed:
    - Create draft PR with suggested changes
    - Comment with downstream impact
    - Request approval before auto-merge

  If no changes:
    - Do nothing

Threshold-based actions

Take different actions based on severity or magnitude:

prompt: |
  Measure documentation coverage.

  If coverage < 50%:
    - Create high-priority issue
    - Send Slack alert to #data-leads
    - Block PR merge

  If coverage 50-80%:
    - Leave PR comment suggesting improvements
    - Don't block merge

  If coverage > 80%:
    - Post positive comment
    - Set status to success

Sequential Actions

Multi-step workflows

Execute actions in a specific order:

prompt: |
  Update documentation workflow:

  1. Profile all changed models using retrieve_metadata
  2. Generate documentation based on profiles
  3. Update YAML files with new descriptions
  4. Run dbt parse to validate changes
  5. If validation passes:
       - Commit changes
       - Create PR
       - Post summary comment
  6. If validation fails:
       - Revert changes
       - Comment with error details

Progressive enhancement

Build up changes through multiple stages:

prompt: |
  Improve model documentation progressively:

  Stage 1: Add basic descriptions
    - Infer purpose from model name and location
    - Add simple descriptions to undocumented models

  Stage 2: Add column details
    - Profile each column
    - Add data types and null rates
    - Note common values for categoricals

  Stage 3: Add relationships
    - Identify joins and dependencies
    - Document relationships to other models
    - Add lineage information

  After all stages:
    - Run comprehensive validation
    - Create PR with all improvements

Approval Workflows

Approval Gates

pattern

Pause execution for human review before sensitive actions.

restrictions:
  approval:
    require_approval_for:
      - pr_creation
      - critical_file_modification
    approvers:
      teams: ["data-platform-leads"]
    approval_timeout_hours: 24
    notification_channel: "#agent-approvals"

prompt: |
  If breaking changes detected:
    1. Analyze impact on downstream dependencies
    2. Generate remediation plan
    3. Request approval to create PR with fixes
    4. Wait for approval (max 24 hours)
    5. If approved: create and merge PR
    6. If denied: comment with explanation and close
    7. If timeout: escalate to #data-platform-leads

Approval process:

Agent pauses at approval point
Notification sent to approvers
Approvers review in web interface
Approval or denial recorded
Agent resumes or aborts accordingly

Approvers see full context: what changed, why, and what action is proposed.

Notification Strategies

Immediate Alerts

Critical Issues

strategy

Send immediate notifications for urgent problems.

prompt: |
  Monitor for critical test failures.

  If severity = "critical":
    - Send Slack to #data-alerts mentioning @oncall
    - Set PR status to failure
    - Block merge
    - Create high-priority issue
    - Send email to [email protected]

  Include in notification:
    - Which tests failed
    - Failure rate and trend
    - Last successful run
    - Likely causes
    - Runbook link

Best for:

Production failures
Data quality issues
Security vulnerabilities
Compliance violations

Batch Reports

Scheduled Summaries

strategy

Aggregate findings and send periodic summaries.

triggers:
  - type: scheduled
    cron: "0 9 * * 1"  # Monday mornings

prompt: |
  Generate weekly documentation coverage report.

  Scan all models and calculate:
    - Overall coverage percentage
    - Coverage by model layer
    - Most improved models this week
    - Models needing attention

  Send report to #data-documentation with:
    - Summary metrics and trends
    - Top 10 undocumented models
    - Team leaderboard for contributions
    - Action items for this week

Best for:

Regular status updates
Trend analysis
Team metrics
Progress tracking

Silent Success, Loud Failure

Asymmetric Notifications

strategy

Only notify when there are issues or changes.

prompt: |
  Update documentation for changed models.

  If updates successful:
    - Create PR (no notifications)
    - Use default reviewers
    - Auto-merge if checks pass

  If updates fail:
    - Comment on PR with failure details
    - Send Slack alert to #data-platform
    - Don't block merge (documentation is nice-to-have)
    - Create issue for manual follow-up

Best for:

Background maintenance
Non-critical automation
High-frequency agents
Self-healing workflows

This reduces notification noise while ensuring visibility when human intervention is needed.

Complete Example

Here’s a comprehensive agent demonstrating multiple actions and notification strategies:

Breaking Change Detector
Drift Monitor

breaking-change-detector.yaml

name: breaking-change-detector
description: Detects and manages breaking changes in mart models

triggers:
  - type: pull_request
    events: [opened, synchronize]
    paths:
      include: ["models/marts/**/*.sql"]

tools:
  preset: standard

restrictions:
  sql:
    read_only: true
  approval:
    require_approval_for: [pr_creation]
    approvers:
      teams: ["data-platform-leads"]

prompt: |
  Analyze this PR for breaking changes in mart models.

  Breaking changes include:
    - Removed columns
    - Renamed columns
    - Changed column data types
    - Modified primary keys
    - Altered join logic

  For each changed mart model:
    1. Compare current version with previous version
    2. Identify all breaking changes
    3. Query metadata to find downstream dependencies
    4. Assess severity:
         - Critical: Affects > 10 dashboards or reports
         - High: Affects 3-10 dependencies
         - Medium: Affects 1-2 dependencies
         - Low: No known dependencies

  If breaking changes found:
    - Leave PR comment:
      **Title:** ⚠️  Breaking Changes Detected

      **Summary:**
      Found {{ breaking_change_count }} breaking changes across {{ model_count }} models.

      **Details:**
      {{ for each breaking change }}
      - **{{ model_name }}**: {{ change_description }}
        - Severity: {{ severity }}
        - Affected: {{ dependency_count }} dependencies
        - Dependents: {{ dependency_list }}
      {{ end for }}

      **Migration Steps:**
      1. {{ suggested_migration_steps }}
      2. Update dependent reports/dashboards
      3. Notify affected teams
      4. Plan deprecation timeline

      **Approval Required:**
      This PR requires review from @data-platform-leads before merging.

    - Set status check:
      - Status: failure
      - Context: "Breaking Change Analysis"
      - Description: "{{ breaking_change_count }} breaking changes found"

    - Send Slack to #data-platform-alerts:
      🚨 **Breaking Changes in PR #{{ pr_number }}**

      **PR:** {{ pr_title }} by @{{ pr_author }}
      **Link:** {{ pr_url }}

      **Impact:**
      • {{ critical_count }} critical changes
      • {{ high_count }} high-severity changes
      • {{ affected_dashboard_count }} dashboards affected

      **Action Required:**
      Review and approval needed from @data-platform-leads

      cc: {{ affected_team_mentions }}

    - If severity >= "High":
      - Create issue:
        - Title: "Migration Plan: {{ pr_title }}"
        - Labels: "breaking-change", "migration-required"
        - Assignees: @data-platform-leads
        - Body: Detailed migration checklist

  If no breaking changes:
    - Set status check:
      - Status: success
      - Context: "Breaking Change Analysis"
      - Description: "No breaking changes detected"

    - Leave brief comment:
      ✅  **No Breaking Changes Detected**

      All changes are backward-compatible.

  If unable to analyze (errors, missing files, etc.):
    - Leave comment:
      ⚠️  **Unable to Complete Analysis**

      Encountered errors during analysis:
      {{ error_details }}

      Please review manually and re-run checks.

    - Set status to "error" (don't block merge)
    - Send Slack to #agent-errors for investigation

Best Practices

Clear Action Specification

Be explicit about what to do

Don’t assume the agent knows your preferences:Vague:

prompt: Let me know if there are issues

Specific:

prompt: |
  If issues found:
    - Comment on PR with file:line references
    - Include code examples of correct syntax
    - Link to relevant style guide section
    - Suggest auto-fixable changes

Specify formatting and structure

Tell agents how to present information:

prompt: |
  Create a summary comment with this structure:

  ## Analysis Results

  **Status:** {{ status_emoji }} {{ status_text }}

  ### Metrics
  | Metric | Value | Change |
  |--------|-------|--------|
  {{ metrics_table }}

  ### Issues Found
  {{ if issues }}
  1. **{{ issue_name }}** (Severity: {{ severity }})
     - Location: `{{ file }}:{{ line }}`
     - Description: {{ description }}
     - Fix: {{ suggested_fix }}
  {{ end for }}
  {{ else }}
  No issues detected ✓
  {{ end if }}

  <details>
  <summary>Full Details</summary>
  {{ detailed_analysis }}
  </details>

Handle all possible outcomes

Cover success, failure, and edge cases:

prompt: |
  Validate model changes.

  If validation passes:
    - Set status to success
    - Post confirmation comment
    - No Slack notification

  If validation fails:
    - Set status to failure with specific errors
    - Comment with failed checks and fixes
    - Send Slack to #data-platform

  If unable to validate (missing dependencies, etc.):
    - Set status to "error"
    - Comment explaining what's missing
    - Don't block merge (validation issue, not code issue)
    - Create issue for infrastructure team

Configuration Over Hardcoding

Use context variables for values that might change, making agents more maintainable.

context:
  vars:
    slack_channel: "#data-alerts"
    critical_mention: "@data-oncall"
    email_recipients: ["[email protected]"]
    severity_thresholds:
      critical: 50
      high: 30
      medium: 20
    runbook_url: "https://wiki.company.com/data/runbooks/drift"

prompt: |
  If deviation_percent > {{ context.vars.severity_thresholds.critical }}:
    - Send Slack to {{ context.vars.slack_channel }}
    - Mention {{ context.vars.critical_mention }}
    - Send email to {{ context.vars.email_recipients }}
    - Link to runbook: {{ context.vars.runbook_url }}

Rate Limit Notifications

Prevent notification fatigue:

restrictions:
  rate_limits:
    max_runs_per_hour: 10
  notifications:
    slack:
      max_messages_per_hour: 5  # Don't spam channels
      dedupe_window_minutes: 30  # Suppress duplicates

prompt: |
  If this is a duplicate alert within 30 minutes:
    - Update existing thread instead of new message
    - Note: "Still occurring at {{ timestamp }}"

Next Steps

Tools & Permissions

Complete guide to agent tools and permissions

Creating Agents

Complete agent configuration guide

Testing & Debugging

Test and debug your agents

Examples

Real-world agent examples

Introduction

Guides

Examples

Resources

Actions & Notifications

How Actions Work

Action Selection

Available Actions

Git Operations

GitHub Status Checks

Slack Notifications

File Operations

Email Notifications

Action Patterns

Conditional Logic

Sequential Actions

Approval Workflows

Notification Strategies

Immediate Alerts

Batch Reports

Silent Success, Loud Failure

Complete Example

Best Practices

Clear Action Specification

Configuration Over Hardcoding

Rate Limit Notifications

Next Steps

Tools & Permissions

Creating Agents

Testing & Debugging

Examples

Introduction

Guides

Examples

Resources

​How Actions Work

​Action Selection

​Available Actions

​Git Operations

​GitHub Status Checks

​Slack Notifications

​File Operations

​Email Notifications

​Action Patterns

​Conditional Logic

​Sequential Actions

​Approval Workflows

​Notification Strategies

​Immediate Alerts

​Batch Reports

​Silent Success, Loud Failure

​Complete Example

​Best Practices

​Clear Action Specification

​Configuration Over Hardcoding

​Rate Limit Notifications

​Next Steps

Tools & Permissions

Creating Agents

Testing & Debugging

Examples

How Actions Work

Action Selection

Available Actions

Git Operations

GitHub Status Checks

Slack Notifications

File Operations

Email Notifications

Action Patterns

Conditional Logic

Sequential Actions

Approval Workflows

Notification Strategies

Immediate Alerts

Batch Reports

Silent Success, Loud Failure

Complete Example

Best Practices

Clear Action Specification

Configuration Over Hardcoding

Rate Limit Notifications

Next Steps