Skip to main content
Integrations allow your agents to communicate with external services and platforms. Whether you need to send notifications to Slack, trigger webhooks, or connect to other tools, the integration system provides a flexible way to handle these interactions.

​
How Integrations Work

The integration system operates on two levels:
  1. Global Integrations: You first create an integration at the organization level. This establishes the connection to the external service (e.g., authenticating with Slack or defining a webhook endpoint).
  2. Agent Notifications: You then “bind” these integrations to specific agents. This allows you to control exactly which agents use which integrations and what events trigger them.

​
Event System

Asteroid Agents emit events throughout their execution lifecycle. You can subscribe to these events to trigger notifications or external workflows.

​
Event Types

​
Execution Status Events

​
Action Events

​
Execution Details Events

​
Filtering & Rules

When adding a notification to an agent, you can control exactly when it triggers using our powerful filtering system.

​
Subscription Modes

  • Subscribe to All: Receive notifications for every event type, including any new event types added in the future.
  • Custom Rules: Select specific event types and optionally add detailed filters.

​
Advanced Filtering

For each event type, you can add one or more Field Filters.
  • OR Logic: If you add multiple filters to a single event type, the notification will trigger if ANY of the filters match.
    • Example: A filter for Outcome equals 'failure' and Outcome equals 'cancelled' effectively means “Notify me if the outcome is failure OR canceled”.
This allows you to create precise rules, such as:
  • “Notify me on ExecutionCompleted only if the result contains ‘Urgent’.”
  • “Notify me on ExecutionFailed or ExecutionCancelled.”

​
Metadata Filtering

In addition to event-type filters, you can filter notifications based on execution metadata. Metadata is a set of key-value pairs that you attach to an execution when you create it (e.g., via the SDK or API). When you add a notification to an agent, you can specify a metadata filter — a set of key-value pairs that must all match the execution’s metadata for the notification to fire.
  • AND Logic: All specified key-value pairs must match. If any pair doesn’t match, the notification is skipped.
  • Empty or omitted: If no metadata filter is set, the notification triggers for all executions regardless of metadata.
  • Extra keys are ignored: The execution can have additional metadata keys beyond those in the filter — only the keys you specify are checked.
Metadata filtering is applied after event-type filtering. An execution must first match the event rules, then match the metadata filter, before a notification is sent.
Example: You run the same agent across multiple environments and only want Slack alerts for production failures:

​
Example Use Case

Most users only want to be notified about critical events—when something goes wrong or when specific outcomes occur.

​
Scenario: Order Processing Agent

Sarah manages an e-commerce agent that processes customer orders hourly. She doesn’t need notifications for every successful order, but she does want alerts for failures and payment issues. Her Configuration:
  1. Creates a Slack integration connected to #operations-alerts
  2. Adds it to her agent with filters:
    • Event: ExecutionFailed - No filters (all failures)
    • Event: ExecutionCompleted - Filter: outcome equals payment_declined
What Happens:
  • Successful orders (outcome: success) → No notification
  • Failed executions → Slack alert: ”🔴 Execution Failed - Payment gateway timeout”
  • Declined payments → Slack alert: ”🟡 Execution Completed - Payment declined for Order #12345”
Result: Sarah’s team receives 5-10 critical notifications per day instead of hundreds.

​
Scenario: Multi-Environment Deployment Agent

Alex runs the same deployment agent across staging and production. He wants a different webhook for each environment. His Configuration:
  1. Creates two webhook integrations: Production Alerts and Staging Alerts
  2. Adds Production Alerts to the agent with:
    • Events: ExecutionFailed, ExecutionCompleted
    • Metadata Filter: environment = production
  3. Adds Staging Alerts to the agent with:
    • Events: ExecutionFailed
    • Metadata Filter: environment = staging
What Happens:
  • Production execution fails → Production Alerts webhook fires
  • Staging execution completes → No notification (staging only alerts on failures)
  • Production execution completes → Production Alerts webhook fires
  • Staging execution fails → Staging Alerts webhook fires
Result: Each environment routes to the right channel with the right level of detail.