> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Learn how to connect Asteroid Agents to external services

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.

<Frame>
  ```mermaid theme={null} theme={null}
  flowchart TD
    Service["External Service (e.g. Slack)"]
    Integration["Integration"]
    NotifA["Notification A"]
    NotifB["Notification B"]
    AgentA["Agent A"]
    AgentB["Agent B"]

    Service <--> Integration
    Integration --> NotifA
    Integration --> NotifB
    NotifA --> AgentA
    NotifB --> AgentB
  ```
</Frame>

## 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`."

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

<Note>
  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.
</Note>

**Example:** You run the same agent across multiple environments and only want Slack alerts for production failures:

| 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:**

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.