Automation Triggers

Automation triggers allow agents to act without a human initiating a conversation. Agents can run on schedules, react to events in conversations, or proactively set up their own automations.

​

Why Automation Triggers?

Without triggers, agents only respond when someone sends them a message. With triggers, agents can:

• Run daily reports at 9 AM
• Monitor conversations for specific topics and react
• Set up their own reminders and scheduled tasks
• Act proactively based on patterns they observe

​

Three Types of Triggers

​

1. Scheduled (Cron)

Time-based triggers that fire on a schedule. Schedule types:

• At — Fire once at a specific date and time, then auto-delete
• Every — Fire repeatedly at a fixed interval (minimum 60 seconds)
• Cron — Standard cron expressions with optional timezone support (5 or 6 field)

When a scheduled trigger fires, it sends the configured prompt to the agent as a new message, and the agent processes it through its full pipeline (model, tools, capabilities).

​

2. Event-Based (Whenhook)

Triggers that evaluate conversation messages against conditions. When a message matches, the trigger fires. Two-layer evaluation: Layer 1 (Prefilter): Fast keyword matching prevents unnecessary LLM calls. Keywords are mandatory — every whenhook must have at least one. Layer 2 (Semantic): An LLM evaluates whether the message truly matches the condition description. The confidence threshold (default: 0.7) controls how certain the LLM must be before firing. Example:

• Keywords: ["deploy", "release", "ship"]
• Condition: "User is discussing a production deployment that needs monitoring"
• A message saying “we just deployed v2.3 to prod” matches keywords and the LLM confirms it’s about a production deployment → trigger fires

​

3. Proactive Automations

When enabled, agents can create their own scheduled and event-based automations using built-in tools. This lets agents set reminders, schedule follow-ups, or watch for conditions — all without human configuration. Agent-accessible tools:

• scheduling_create / scheduling_list / scheduling_get / scheduling_cancel — Manage scheduled automations
• whenhook_create / whenhook_list / whenhook_remove — Manage event-based automations

​

Actions

When a trigger fires, it executes an action:

• AgentRun — Sends a prompt to the agent, which processes it as a normal conversation turn
• WorkflowRun — Starts a workflow execution with specified input

​

Safety and Limits

Automation triggers include multiple layers of protection:

​

Layer 1: Creation Quotas

​

Layer 2: Daily Firing Budget

Daily budgets reset at midnight UTC. Both scheduled and event firings count toward the same budget.

​

Layer 3: Safety Controls

​

Active Hours

Any automation can be restricted to fire only during specific hours:

• Start hour and end hour (0–23)
• IANA timezone (e.g., America/New_York)
• Automations outside active hours are skipped

​

Expiration

Automations can have an optional expires_at timestamp. After expiration, the automation is automatically disabled.

​

Execution Flow

​

Scheduled Triggers

​

Event Triggers

Event evaluation runs asynchronously after a conversation turn completes — it doesn’t block agent responses.

​

Configuration

Each agent has a TriggerConfig with independent toggles:

• Enabled (master switch) — Must be on for any triggers to work
• Scheduled (Cron) — Enable time-based triggers
• Event-Based (Whenhook) — Enable conversation event triggers
• Proactive Automations — Allow the agent to self-create automations

All toggles default to off. Enable only what you need.

---

Next: Learn how to configure automation triggers for your agents.