Core Concepts

Proactive Agents

Build agents that act autonomously without waiting for user input.

What are Proactive Agents?

Unlike reactive agents that respond to user messages, proactive agents can:

Run on a schedule (e.g., every hour, daily at 9am)
React to external events (webhooks, API triggers)
Monitor conditions and act when thresholds are met

The Pulse Engine

The Pulse Engine is BotHive's heartbeat that wakes up proactive agents. It continuously checks for scheduled jobs and triggers bot execution.

Pulse Engine runs every 60 seconds

Scheduled Execution

Use a schedule block with a cron expression to run code at specific intervals.

scheduled-bot.hive

bot DailyDigest {
  instructions {
    Sends a daily summary email.
  }

  capabilities {
    web.search
    email.send
  }

  // Runs every day at 9am.
  schedule MorningDigest at "0 9 * * *" {
    call web.search with { query: "tech news today" } as news
    call email.send with {
      to: "user@bothive.cloud",
      subject: "Your Daily Tech Digest",
      body: news
    }
  }
}

Event-Driven Triggers

Proactive agents can also respond to external events like GitHub webhooks, Slack mentions, or custom API calls.

event-bot.hive

bot PRReviewer {
  instructions {
    Reviews new pull requests.
  }

  capabilities {
    code.analyze
    github.comment
  }

  on github.pull_request.opened {
    // The event payload (repo, PR number, author, ...) arrives as input.
    call code.analyze with { pr: input } as analysis
    call github.comment with { pr: input, body: analysis }
  }
}

Configuring Schedules

Set up proactive behavior in the bot settings or via the API:

proactive-config.json

{
  "schedule": "0 9 * * *",  // Every day at 9am
  "events": ["github.push", "slack.mention"],
  "enabled": true
}