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:
- 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).
- 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 Type | Description |
|---|
ExecutionStarted | Triggered when an agent begins a new execution. |
ExecutionCompleted | Triggered when an agent successfully completes its task. |
ExecutionFailed | Triggered when an agent encounters an error and fails. |
ExecutionCancelled | Triggered when an execution is cancelled (by user, timeout, or max steps). |
ExecutionPaused | Triggered when an agent pauses (e.g., waiting for user input). |
ExecutionResumed | Triggered when a paused agent resumes execution. |
ExecutionAwaitingConfirmation | Triggered when an agent needs confirmation before proceeding (e.g., “Human in the Loop”). |
Action Events
| Event Type | Description |
|---|
ExecutionActionStarted | Triggered when an action within execution has started. |
ExecutionActionFailed | Triggered when an action within execution fails. |
Execution Details Events
| Event Type | Description |
|---|
ExecutionStepStarted | Triggered when a step in the execution starts. |
ExecutionWorkflowUpdated | Triggered when the execution workflow is updated. |
UserMessageReceived | Triggered 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.”
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.
| Execution Metadata | Metadata Filter | Result |
|---|
environment: production | environment: production | Notification sent |
environment: staging | environment: production | Skipped |
environment: production, region: us-east | environment: production | Notification sent (extra keys ignored) |
environment: production | environment: production, team: payments | Skipped (team key missing) |
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:
- Creates a Slack integration connected to
#operations-alerts
- 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:
- Creates two webhook integrations:
Production Alerts and Staging Alerts
- Adds
Production Alerts to the agent with:
- Events:
ExecutionFailed, ExecutionCompleted
- Metadata Filter:
environment = production
- 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. 
