Skip to content

AUTOMATIONS.md

Latest commit

 

History

History
1193 lines (903 loc) · 35.5 KB

AUTOMATIONS.md

File metadata and controls

1193 lines (903 loc) · 35.5 KB
Raw

Automations

Automations allow you to create IFTTT/Zapier-style workflows that trigger actions based on events, schedules, or webhooks. Use automations to have AI agents respond to mentions, send notifications to external systems, or orchestrate complex workflows.

Table of Contents

Overview

What Are Automations?

Automations are rules that execute actions when specific conditions are met. Each automation has:

  1. Trigger - What starts the automation (event, schedule, webhook, or manual)
  2. Conditions (optional) - Filters that must pass for the automation to run
  3. Actions - What happens when the automation runs

Types of Automations

Type Scope Use Case
Agent Automations AI Agent Trigger an agent to perform tasks (e.g., respond to @mentions)
Collective Automations Collective Send webhooks, trigger agents, or orchestrate workflows
Notification Webhooks User or AI Agent Forward all of a recipient's notifications to one external URL (see Notification Webhooks)

Billing Gate

Automations are a paid feature. On billing-enabled tenants, events on collectives that aren't paid-tier (or the main collective) match no rules — a lapsed billing state pauses automation execution without touching rule configuration, so restoring billing resumes them instantly. Notification webhooks are exempt from this gate: they forward a notification system the user already has, and chat collectives are free-tier.

How It Works

Trigger occurs (event/schedule/webhook/manual)
        ↓
Automation engine finds matching rules
        ↓
Conditions evaluated (all must pass)
        ↓
Actions executed (webhooks, agent tasks, etc.)
        ↓
Run recorded for auditing

Quick Start

Creating Your First Agent Automation

  1. Navigate to your AI agent's page
  2. Click Automations in the sidebar
  3. Click New Automation or choose from Templates
  4. Enter your YAML configuration:
name: "Respond to Mentions"
description: "Trigger when the agent is @mentioned"

trigger:
  type: event
  event_type: note.created
  mention_filter: self

task: |
  You were mentioned by {{event.actor.name}}.
  Navigate to {{subject.path}} and respond appropriately.

max_steps: 20
  1. Click Create to save
  2. The automation is now active and will trigger when someone @mentions your agent

Creating a Collective Automation

  1. Go to Collective Settings → Automations
  2. Click New Automation
  3. Configure your webhook or multi-action workflow:
name: "Slack Notification"
description: "Notify Slack when decisions are created"

trigger:
  type: event
  event_type: decision.created

actions:
  - type: webhook
    url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
    method: POST
    payload:
      text: "New decision: {{subject.title}}"
      blocks:
        - type: section
          text:
            type: mrkdwn
            text: "Created by {{event.actor.name}}"

Trigger Types

Event Triggers

Event triggers fire when something happens in the collective--a note is created, a decision is made, or a commitment reaches critical mass.

trigger:
  type: event
  event_type: note.created      # Required: which event to listen for
  mention_filter: self          # Optional: filter by @mentions

Supported Event Types

Event Type When It Fires
note.created A new top-level note is posted
comment.created A comment (or reply) is added to content
decision.created A new decision is created
option.created An option is added to a decision
vote.created A vote is cast on a decision option
decision.deadline_reached A decision's deadline passes (the decision is resolved)
commitment.created A new commitment is created
commitment.joined A participant joins a commitment
commitment.critical_mass A commitment's committed count reaches its critical mass threshold
commitment.deadline_reached A commitment's deadline passes
chat_message.created A chat message is sent
user_list_member.created A user is added to a list

Notes, comments, decisions, commitments, options, votes, chat messages, and list memberships also emit .updated and .deleted variants (where the model supports updates). Comments are stored as notes but emit comment.*, not note.* — a rule on note.created does not fire for comments.

notifications.delivered and reminders.delivered are special-cased for notification webhooks and are not intended for general rules.

Rules store a single event_type in YAML. Internally, system-managed rules may use the event_types array form to match several types with one rule (e.g. the built-in personas' mentions-and-replies rules match both note.created and comment.created); the matching scope (AutomationRule.for_event_type) understands both forms.

Mention Filters

For agent automations, you can filter by @mentions:

Filter Behavior
self Only trigger if this agent is @mentioned
self_or_reply Trigger if this agent is @mentioned, or the event's subject is a comment on content this agent created
any_agent Trigger if any AI agent is @mentioned
(blank) No mention filtering—triggers on all matching events 
# Only trigger when someone @mentions this specific agent
trigger:
  type: event
  event_type: note.created
  mention_filter: self

Schedule Triggers

Schedule triggers run on a cron schedule—daily summaries, weekly reviews, or any recurring task.

trigger:
  type: schedule
  cron: "0 9 * * *"              # Required: 5-field cron expression
  timezone: "America/Los_Angeles" # Optional: defaults to UTC

Cron Expression Format

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Examples:

Cron Schedule
0 9 * * * Every day at 9:00 AM
0 9 * * 1 Every Monday at 9:00 AM
0 9 1 * * First day of every month at 9:00 AM
*/15 * * * * Every 15 minutes
0 */2 * * * Every 2 hours

Webhook Triggers

Webhook triggers allow external systems to trigger your automations via HTTP POST.

trigger:
  type: webhook
  allowed_ips:                   # Optional: restrict by IP
    - "192.168.1.0/24"
    - "10.0.0.1"

When you create a webhook-triggered automation, the system generates:

  • Webhook URL: A unique tenant-scoped endpoint, https://{tenant}.{host}/hooks/{webhook_path}
  • Webhook Secret: For HMAC signature verification

Sending Webhooks to Your Automation

External systems should:

  1. POST JSON to your webhook URL
  2. Include a Unix timestamp in the X-Harmonic-Timestamp header
  3. Include the HMAC signature in the X-Harmonic-Signature header — HMAC-SHA256 of "{timestamp}.{body}" with the webhook secret
  4. (Optional) Send from allowed IP addresses

Timestamps older than 5 minutes are rejected (replay protection).

# Example: calling your webhook
SECRET="your-webhook-secret"
PAYLOAD='{"action": "deploy", "version": "1.2.3"}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(echo -n "${TIMESTAMP}.${PAYLOAD}" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)

curl -X POST "https://yourtenant.yourapp.com/hooks/abc123xyz789" \
  -H "Content-Type: application/json" \
  -H "X-Harmonic-Timestamp: $TIMESTAMP" \
  -H "X-Harmonic-Signature: sha256=$SIGNATURE" \
  -d "$PAYLOAD"

The automation's detail page shows the exact URL, headers, and working curl/Ruby examples for that rule.

Manual Triggers

Manual triggers don't fire automatically—they're executed on-demand via the UI.

trigger:
  type: manual
  inputs:                        # Optional: define input fields
    title:
      type: string
      label: "Note Title"
      default: "Untitled"
    priority:
      type: number
      label: "Priority (1-10)"
      default: 5
    urgent:
      type: boolean
      label: "Mark as Urgent?"
      default: false

Input Types

Type Description
string Text input
number Numeric input
boolean Checkbox (true/false)

Manual triggers are useful for:

  • One-click workflows
  • Administrative tasks
  • Testing before converting to automatic triggers

Actions

Agent Automations (Task-Based)

Agent automations use a task field instead of actions. The task describes what the agent should do:

task: |
  You were mentioned by {{event.actor.name}} in {{subject.path}}.
  Navigate there, read the context, and respond appropriately.

max_steps: 20  # Optional: limit agent steps (default varies)

The agent receives the rendered task prompt and executes autonomously.

Collective Automations (Action-Based)

Collective automations use an actions array with multiple action types:

Webhook Actions

Send HTTP requests to external systems:

actions:
  - type: webhook
    url: "https://api.example.com/notify"
    method: POST                  # Optional: GET, POST, PUT, PATCH, DELETE
    headers:                      # Optional: custom headers
      Authorization: "Bearer {{secrets.api_token}}"
      X-Custom-Header: "value"
    payload:                      # Request body (JSON)
      event_type: "{{event.type}}"
      actor: "{{event.actor.name}}"
      content: "{{subject.text}}"
    timeout: 30                   # Optional: timeout in seconds

Trigger Agent Actions

Trigger an AI agent to perform a task:

actions:
  - type: trigger_agent
    agent_id: "agent-uuid-here"   # Required: agent's ID
    task: |                       # Required: task description
      Review the new content at {{subject.path}}.
      Post a summary of the key points.
    max_steps: 15                 # Optional: limit steps

Internal Actions

Create content directly within the collective. Internal actions execute as the collective identity user and are automatically tracked for attribution.

Supported Actions:

Action Description Required Params
create_note Create a new note text
create_decision Create a new decision question
create_commitment Create a new commitment title, critical_mass 
actions:
  # Create a note
  - type: internal_action
    action: create_note
    params:
      text: "Automated response to: {{subject.title}}"
      title: "Automation Summary"  # Optional

  # Create a decision
  - type: internal_action
    action: create_decision
    params:
      question: "Should we proceed with {{subject.title}}?"
      description: "Auto-generated decision for review"  # Optional
      deadline: "2026-12-31"  # Optional
      options: ["Yes", "No", "Discuss further"]  # Optional initial options

  # Create a commitment
  - type: internal_action
    action: create_commitment
    params:
      title: "Follow up on {{subject.title}}"
      description: "Automated commitment"  # Optional
      critical_mass: 3  # Required
      deadline: "2026-12-31"  # Optional
      limit: 10  # Optional max participants

Resource Tracking: All resources created by internal actions are tracked and display an "Created by automation" attribution badge linking back to the automation rule and run.

Multiple Actions

You can chain multiple actions in a single automation:

actions:
  # First, notify Slack
  - type: webhook
    url: "https://hooks.slack.com/services/..."
    payload:
      text: "New decision created"

  # Then, have an agent summarize
  - type: trigger_agent
    agent_id: "summarizer-agent-id"
    task: "Summarize the decision at {{subject.path}}"

Notification Webhooks

Notification webhooks are a managed, per-recipient webhook surface, distinct from the rule-authored webhooks above: one webhook per user or agent, forwarding all of that recipient's notifications (mentions, comments, participation, reminders, chat messages, tune-ins) to a single external URL.

  • Configured in their own UI — /u/{handle}/webhook for users, the agent's settings page for agents — not via automation YAML.
  • Implemented internally as a special automation rule triggered by notifications.delivered / reminders.delivered events. For these events the event actor is the recipient being notified (not the originator), so the usual self-trigger guard on agent rules does not block them.
  • Excluded from general automation listings; uniqueness is enforced per recipient per tenant.
  • Exempt from the paid-tier gate (see Billing Gate).
  • Rate-limited at 3 deliveries/minute per recipient, with a fast-path check so the high-volume delivery events cost nothing for recipients without a webhook.

Deliveries are signed the same way as rule webhooks (X-Harmonic-Timestamp + X-Harmonic-Signature over "{timestamp}.{body}"), with secret rotation and test-delivery support in the UI.

Conditions

Conditions filter which events trigger your automation. All conditions must pass (AND logic).

conditions:
  - field: "event.actor.id"
    operator: "!="
    value: "bot-user-id"          # Don't trigger on bot posts

  - field: "subject.text"
    operator: "contains"
    value: "urgent"               # Only trigger on urgent content

Operators

Operator Description Example
== Equals value: "active"
!= Not equals value: "draft"
> Greater than (numeric) value: 5
>= Greater than or equal value: 10
< Less than value: 100
<= Less than or equal value: 50
contains String contains substring value: "error"
not_contains String doesn't contain value: "test"
matches Regex pattern match value: "^error.*"
not_matches Regex doesn't match value: "\\[draft\\]"

Field Paths

Use dot notation to access nested fields:

conditions:
  - field: "event.actor.name"        # Actor's name
    operator: "=="
    value: "Alice"

  - field: "subject.created_by.id"   # Content creator's ID
    operator: "!="
    value: "system"

  - field: "event.metadata.priority" # Custom event metadata
    operator: ">="
    value: 5

Template Variables

Use {{variable}} syntax to insert dynamic values into your tasks, payloads, and conditions.

Note: Complex values (objects and arrays) are automatically JSON-encoded when rendered. For example, {{payload.data}} containing {"key": "value"} renders as the JSON string {"key":"value"}, not Ruby's hash format.

Event Context

Available when trigger type is event:

# Event information
{{event.type}}              # e.g., "note.created"
{{event.created_at}}        # ISO8601 timestamp

# Actor (who triggered the event)
{{event.actor.id}}
{{event.actor.name}}
{{event.actor.handle}}

# Subject (what the event is about)
{{subject.id}}
{{subject.type}}            # e.g., "note", "decision"
{{subject.path}}            # URL path, e.g., "/n/abc123"
{{subject.title}}           # Title or summary
{{subject.text}}            # Full text content

# Subject creator
{{subject.created_by.id}}
{{subject.created_by.name}}
{{subject.created_by.handle}}

# Collective context
{{collective.id}}
{{collective.name}}
{{collective.handle}}
{{collective.path}}

Webhook Context

Available when trigger type is webhook:

# Raw webhook payload (access any field)
{{payload.action}}
{{payload.data.id}}
{{payload.nested.deeply.value}}

# Webhook metadata
{{webhook.path}}
{{webhook.received_at}}
{{webhook.source_ip}}

Schedule Context

Available when trigger type is schedule:

{{schedule.triggered_at}}    # When the schedule fired

Manual Input Context

Available when trigger type is manual:

{{inputs.title}}             # User-provided input values
{{inputs.priority}}
{{inputs.urgent}}

Using Variables in Tasks

task: |
  You were mentioned by {{event.actor.name}} in a {{subject.type}}.

  Content: {{subject.text}}

  Navigate to {{subject.path}} and respond appropriately.
  Be professional and helpful.

Using Variables in Webhooks

actions:
  - type: webhook
    url: "https://api.example.com/events"
    payload:
      event_type: "{{event.type}}"
      actor_name: "{{event.actor.name}}"
      content:
        id: "{{subject.id}}"
        type: "{{subject.type}}"
        text: "{{subject.text}}"

Examples

Example 1: Agent Responds to @Mentions

The most common use case—an AI agent that responds when mentioned.

name: "Respond to Mentions"
description: "Reply when someone @mentions this agent"

trigger:
  type: event
  event_type: note.created
  mention_filter: self

task: |
  Someone mentioned you in {{subject.path}}.

  They said: "{{subject.text}}"

  Navigate there and provide a helpful, relevant response.
  Consider the context of the conversation.

max_steps: 20

Example 2: Daily Collective Summary

An agent that posts a daily summary every morning.

name: "Daily Summary"
description: "Post a summary of yesterday's activity"

trigger:
  type: schedule
  cron: "0 9 * * *"
  timezone: "America/New_York"

task: |
  It's time for the daily summary.

  Review yesterday's activity in the collective:
  - New notes and discussions
  - Decisions made or pending
  - Commitments created or completed

  Post a concise summary highlighting the most important items.
  Tag any items that need attention.

max_steps: 30

Example 3: Decision Helper

An agent that helps analyze new decisions when mentioned.

name: "Decision Analysis"
description: "Analyze decisions when mentioned"

trigger:
  type: event
  event_type: decision.created
  mention_filter: self

task: |
  A new decision was created and you were asked to help.

  Decision: {{subject.title}}

  Navigate to {{subject.path}} and:
  1. Analyze the decision and its options
  2. Consider pros and cons of each option
  3. Post your analysis as a comment

  Be objective and thorough.

max_steps: 25

Example 4: Slack Notification for Critical Mass

Notify Slack when commitments reach their threshold.

name: "Critical Mass Notification"
description: "Notify Slack when commitments hit critical mass"

trigger:
  type: event
  event_type: commitment.critical_mass

actions:
  - type: webhook
    url: "https://hooks.slack.com/services/T00/B00/XXX"
    method: POST
    payload:
      text: "Commitment reached critical mass!"
      blocks:
        - type: section
          text:
            type: mrkdwn
            text: "*{{subject.title}}*\nReached critical mass"
        - type: context
          elements:
            - type: mrkdwn
              text: "Created by {{subject.created_by.name}}"

Example 5: Filtered Comment Response

Only respond to comments that mention "help" or "question".

name: "Help Response"
description: "Respond to comments asking for help"

trigger:
  type: event
  event_type: comment.created
  mention_filter: self

conditions:
  - field: "subject.text"
    operator: "matches"
    value: "(?i)(help|question|how do|what is)"

task: |
  Someone needs help! They commented: "{{subject.text}}"

  Navigate to {{subject.path}} and provide a helpful response.
  Be patient and thorough in your explanation.

max_steps: 20

Example 6: External System Integration

Trigger automation from an external CI/CD system.

name: "Deploy Notification"
description: "Receive deployment notifications"

trigger:
  type: webhook
  allowed_ips:
    - "10.0.0.0/8"

actions:
  - type: trigger_agent
    agent_id: "deployment-agent-uuid"
    task: |
      A deployment was just completed.

      Version: {{payload.version}}
      Environment: {{payload.environment}}
      Deployer: {{payload.deployer}}

      Post a summary to the team and highlight any breaking changes.

Example 7: Weekly Review Workflow

Multi-action workflow for weekly planning.

name: "Weekly Review"
description: "Monday morning review workflow"

trigger:
  type: schedule
  cron: "0 8 * * 1"
  timezone: "America/Los_Angeles"

actions:
  # First, have the review agent compile notes
  - type: trigger_agent
    agent_id: "reviewer-agent-uuid"
    task: |
      It's Monday morning. Review last week's activity:
      - Completed commitments
      - Open decisions
      - Unresolved discussions

      Post a weekly review note summarizing status.

  # Then, notify the team via Slack
  - type: webhook
    url: "https://hooks.slack.com/services/..."
    payload:
      text: "Weekly review is ready! Check the collective for the summary."

YAML Schema Reference

Complete Schema

# Required
name: string                        # Rule name (displayed in UI)

# Optional
description: string                 # Description of what the rule does

# Required: Trigger configuration
trigger:
  type: enum                        # "event" | "schedule" | "webhook" | "manual"

  # For type: event
  event_type: string                # Required for events
  mention_filter: enum              # Optional: "self" | "self_or_reply" | "any_agent"

  # For type: schedule
  cron: string                      # Required: 5-field cron expression
  timezone: string                  # Optional: IANA timezone (default: UTC)

  # For type: webhook
  allowed_ips: [string]             # Optional: IP addresses or CIDR ranges

  # For type: manual
  inputs:                           # Optional: input field definitions
    <field_name>:
      type: enum                    # "string" | "number" | "boolean"
      label: string                 # Display label
      default: any                  # Default value

# For Agent Rules (mutually exclusive with actions)
task: string                        # Task prompt with {{variables}}
max_steps: integer                  # Optional: max agent steps

# For Collective Rules (mutually exclusive with task)
actions:                            # Array of actions
  - type: enum                      # "webhook" | "trigger_agent" | "internal_action"

    # For type: webhook
    url: string                     # Required: endpoint URL
    method: enum                    # Optional: GET|POST|PUT|PATCH|DELETE (default: POST)
    headers: object                 # Optional: custom headers
    payload: object                 # Optional: request body (alias: body)
    timeout: integer                # Optional: timeout in seconds (default: 30)

    # For type: trigger_agent
    agent_id: string                # Required: agent UUID
    task: string                    # Required: task prompt
    max_steps: integer              # Optional: max steps

    # For type: internal_action (see detailed schemas below)
    action: enum                    # "create_note" | "create_decision" | "create_commitment"
    params: object                  # Action-specific parameters (see below)

# Optional: Conditions (all must pass)
conditions:
  - field: string                   # Dot-notation path (e.g., "event.actor.id")
    operator: enum                  # ==|!=|>|>=|<|<=|contains|not_contains|matches|not_matches
    value: any                      # Value to compare against

Validation Rules

  1. Name is required
  2. Trigger is required with valid type
  3. Event triggers require event_type
  4. Schedule triggers require valid cron expression
  5. Agent rules must have task, cannot have actions
  6. Collective rules must have actions, cannot have task
  7. Mention filters must be "self", "self_or_reply", or "any_agent"
  8. Conditions must use valid operators
  9. Webhook IPs must be valid IPv4/IPv6 or CIDR notation

Internal Action Schemas

Internal actions create content in the collective. Each action has specific required and optional parameters.

create_note

Creates a new note in the collective.

actions:
  - type: internal_action
    action: create_note
    params:
      text: string        # REQUIRED - The note content (supports {{variables}})
      title: string       # Optional - Note title (auto-generated from text if omitted)

Minimal example:

actions:
  - type: internal_action
    action: create_note
    params:
      text: "Daily standup summary for {{schedule.triggered_at}}"

Full example:

actions:
  - type: internal_action
    action: create_note
    params:
      text: |
        ## Summary
        New content was created by {{event.actor.name}}.

        Original: {{subject.text}}
      title: "Auto-summary: {{subject.title}}"

create_decision

Creates a new decision for the collective to vote on.

actions:
  - type: internal_action
    action: create_decision
    params:
      question: string      # REQUIRED - The decision question
      description: string   # Optional - Additional context
      deadline: string      # Optional - ISO8601 date (e.g., "2026-12-31")
      options: [string]     # Optional - Initial option titles to add

Minimal example:

actions:
  - type: internal_action
    action: create_decision
    params:
      question: "Should we proceed with this proposal?"

Full example:

actions:
  - type: internal_action
    action: create_decision
    params:
      question: "How should we handle {{subject.title}}?"
      description: |
        This decision was auto-generated based on {{event.type}}.
        Please review and vote.
      deadline: "2026-12-31"
      options:
        - "Approve as-is"
        - "Request changes"
        - "Defer to next cycle"

create_commitment

Creates a new commitment for collective members to join.

actions:
  - type: internal_action
    action: create_commitment
    params:
      title: string           # REQUIRED - The commitment title
      description: string     # Optional - Additional context
      critical_mass: integer  # REQUIRED - Minimum participants needed
      deadline: string        # Optional - ISO8601 date (e.g., "2026-12-31")
      limit: integer          # Optional - Maximum participants allowed

Minimal example:

actions:
  - type: internal_action
    action: create_commitment
    params:
      title: "Review the weekly summary"
      critical_mass: 1

Full example:

actions:
  - type: internal_action
    action: create_commitment
    params:
      title: "Participate in {{subject.title}}"
      description: |
        Auto-generated commitment for the upcoming event.
        Join to confirm your participation.
      critical_mass: 5
      deadline: "2026-12-31"
      limit: 20

Testing Automations

Using the Test Feature

Collective automations have a Test button that:

  1. Creates a synthetic test event
  2. Executes the automation immediately
  3. Shows results including:
    • Whether conditions passed
    • Actions executed
    • Webhook responses
    • Any errors

Test Behavior by Trigger Type

Trigger Type Test Behavior
Event Creates fake event with test metadata
Schedule Records current time as trigger time
Webhook Generates example payload
Manual Uses provided or default input values

Viewing Run History

Both agent and collective automations have a Runs tab showing:

  • Trigger source (event, schedule, webhook, manual, test)
  • Status (pending, running, completed, failed, skipped)
  • Execution time
  • Actions executed
  • Error messages (if any)

Click a run to see detailed information including webhook delivery status.

Resource Tracking

When automations create content (via internal actions or AI agents), those resources are tracked for traceability:

  1. Attribution Badge: Created notes, decisions, and commitments display a "Created by automation" badge
  2. Link to Rule: Badge links to the automation rule that created it
  3. Link to Run: Badge also links to the specific run for debugging
  4. Run Details: The run detail page shows all resources created during that execution

This tracking helps you:

  • Understand which content was auto-generated
  • Debug automation behavior
  • Audit automation activity
  • Navigate from created content back to its source

Tracked Resource Types:

  • Notes (created, updated)
  • Decisions (created)
  • Commitments (created)
  • Options (added to decisions)
  • Votes (cast on options)
  • Commitment participants (joined)

Rate Limits & Chain Protection

Automations have multiple layers of protection to prevent runaway execution and system overload.

Rate Limits

Limit Type Value Scope
Tenant-level 100 runs/minute All automations across the tenant
Agent rules 3 runs/minute Per individual agent automation
Collective rules 10 runs/minute Per individual collective automation
Notification webhooks 3 deliveries/minute Per recipient webhook

When a rate limit is hit:

  • The automation execution is silently skipped
  • A metric is emitted for monitoring (see Monitoring)
  • The event/trigger is not retried

Chain Protection

When automations trigger other automations (e.g., an automation creates a note that triggers another automation), chain limits prevent infinite loops and cascade explosions.

Protection Limit Description
Chain depth 3 levels Max nesting of automation → automation calls
Rules per chain 10 Max total rules that can execute in one chain
Loop detection Per rule Same rule cannot execute twice in one chain

Example chain:

Event occurs
  → Automation A triggers (depth 1)
    → Creates note that triggers Automation B (depth 2)
      → That triggers Automation C (depth 3)
        → Any further triggers are blocked (depth limit)

Monitoring

Automation metrics are exposed via Prometheus for operational monitoring.

Available Metrics

Metric Type Tags Description
automations_runs_total Counter tenant_id, rule_type, trigger_type, status Total automation runs
automations_rate_limited_total Counter tenant_id, limit_type, rule_type Executions blocked by rate limits
automations_chain_blocked_total Counter tenant_id, block_reason Executions blocked by chain protection

Example Queries

# Rate limit hits per tenant in last hour
sum by (tenant_id, limit_type) (increase(automations_rate_limited_total[1h]))

# Chain blocks by reason
sum by (block_reason) (increase(automations_chain_blocked_total[1h]))

# Automation runs by status
sum by (status) (increase(automations_runs_total[1h]))

Alerting Recommendations

  • High rate limit hits: May indicate runaway automation or need to adjust limits
  • Chain depth blocks: May indicate unintended automation loops
  • Loop detection blocks: Definitely indicates a configuration issue to fix

Troubleshooting

Automation Not Triggering

  1. Check if enabled: Automations can be toggled on/off
  2. Verify event type: Make sure you're listening for the right event
  3. Check mention filter: If using mention_filter: self, ensure the agent is actually @mentioned
  4. Review conditions: Conditions may be filtering out events
  5. Check rate limits: See Rate Limits - agent rules: 3/min, collective rules: 10/min, tenant: 100/min
  6. Check chain limits: If triggered by another automation, chain depth (3) or rules-per-chain (10) may be exceeded

Webhook Actions Failing

  1. Check URL: Ensure the URL is correct and accessible
  2. Verify payload: Use the test feature to see the rendered payload
  3. Check response: View run details for HTTP status codes
  4. Review headers: Authentication headers may be missing

Agent Not Responding

  1. Check task prompt: Ensure the prompt is clear and actionable
  2. Verify max_steps: Agent may be hitting step limit
  3. Review agent state: Check if the agent is enabled and configured
  4. Check linked run: View the AI agent task run for details

Internal Actions Failing

  1. Check collective context: Internal actions require a collective automation (not user-level)
  2. Verify identity user: Collective must have an identity user configured
  3. Check required params: Each action has required parameters (see table above)
  4. Review run details: Check the run's executed actions for specific errors

Template Variables Not Rendering

  1. Check syntax: Use {{variable}} not {variable} or {{ variable }}
  2. Verify path: Use dot notation for nested fields
  3. Check context: Different trigger types have different available variables
  4. Test with simple values: Start with {{event.type}} to verify rendering works

Common Error Messages

Error Cause Solution
"Invalid YAML syntax" YAML parsing failed Check indentation and quotes
"Event type is required" Missing event_type for event trigger Add event_type field
"Invalid cron expression" Malformed cron schedule Use 5-field cron format
"Agent not found" Invalid agent_id in trigger_agent Verify agent UUID exists
"Rate limit exceeded" Too many executions Agent: 3/min, Collective: 10/min, Tenant: 100/min
"Internal actions require a collective context" User-level automation with internal_action Use collective automation instead
"Unsupported action" Invalid action name Use create_note, create_decision, or create_commitment
"Collective does not have an identity user" Missing identity user Contact admin to configure collective

Best Practices

Writing Effective Agent Tasks

  1. Be specific: Tell the agent exactly what to do
  2. Provide context: Include relevant information from template variables
  3. Set expectations: Describe the desired outcome
  4. Limit scope: Use max_steps to prevent runaway executions
# Good
task: |
  You were mentioned in {{subject.path}}.
  Read the note and post a concise response.
  Focus on answering any questions asked.
  Keep your response under 200 words.

# Less effective
task: |
  Respond to the mention.

Webhook Best Practices

  1. Use HTTPS: Always use secure endpoints
  2. Handle failures: External systems should be resilient to delivery failures
  3. Verify signatures: Validate HMAC signatures for security
  4. Use timeouts: Set appropriate timeouts for slow endpoints

Condition Best Practices

  1. Filter early: Use conditions to reduce unnecessary executions
  2. Test patterns: Verify regex patterns before deploying
  3. Consider edge cases: What if the field is missing or empty?

General Tips

  1. Start simple: Begin with basic automations and iterate
  2. Use templates: Start from the template gallery for common patterns
  3. Test before enabling: Use the test feature to verify behavior
  4. Monitor runs: Check run history for unexpected failures
  5. Document purpose: Use the description field to explain intent