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

Event TypeDescription
ExecutionStartedTriggered when an agent begins a new execution.
ExecutionCompletedTriggered when an agent successfully completes its task.
ExecutionFailedTriggered when an agent encounters an error and fails.
ExecutionCancelledTriggered when an execution is cancelled (by user, timeout, or max steps).
ExecutionPausedTriggered when an agent pauses (e.g., waiting for user input).
ExecutionResumedTriggered when a paused agent resumes execution.
ExecutionAwaitingConfirmationTriggered when an agent needs confirmation before proceeding (e.g., “Human in the Loop”).

​
Action Events

Event TypeDescription
ExecutionActionStartedTriggered when an action within execution has started.
ExecutionActionFailedTriggered when an action within execution fails.

​
Execution Details Events

Event TypeDescription
ExecutionStepStartedTriggered when a step in the execution starts.
ExecutionWorkflowUpdatedTriggered when the execution workflow is updated.
UserMessageReceivedTriggered when the agent receives a message from the user.

​
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 cancelled”.
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.”

​
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.