# Agent Event

Listen to agent lifecycle, UI, and conversation events from your app with .on() and .off().

Subscribe to agent lifecycle, UI, and conversation events directly from your app.

:::note[Prerequisites]
The [SDK is installed and initialized](/start/install/). Call these methods inside the `foldspace('when', 'ready', ...)` callback.
:::

## Subscribe to events

### `on(event, handler)` / `off(event, handler)`

```javascript
foldspace.agent("AGENT_NAME").on(event, handler);
foldspace.agent("AGENT_NAME").off(event, handler);
```

| Parameter | Type | Description |
| --- | --- | --- |
| `event` | string | The event name. |
| `handler` | function | Callback that receives the event payload. |

Both `.on()` and `.off()` return the agent instance, so calls can be chained.

## Available events

### Agent lifecycle

| Event | Payload | Description |
| --- | --- | --- |
| `agent.ready` | `{}` | Fired when the agent is fully initialized and ready. |
| `agent.removed` | `{}` | Fired when the agent is removed from the page. |

### UI lifecycle

| Event | Payload | Description |
| --- | --- | --- |
| `ui.open` | `{ rect: DOMRect }` | Fired when the chat UI is opened. |
| `ui.close` | `{ rect: DOMRect }` | Fired when the chat UI is closed. |
| `ui.show` | `{ rect: DOMRect }` | Fired when the agent becomes visible. |
| `ui.hide` | `{ rect: DOMRect }` | Fired when the agent is hidden. |
| `ui.move` | `{ rect: DOMRect }` | Fired when the agent is dragged to a new position. |
| `ui.resize` | `{ rect: DOMRect }` | Fired when the agent is resized. |

### Conversation lifecycle

| Event | Payload | Description |
| --- | --- | --- |
| `conversation.created` | `{ conversationId: string }` | Fired when a new conversation is created. |

### Action callback lifecycle

| Event | Payload | Description |
| --- | --- | --- |
| `action.callback` | `{ actionKey: string; status: "executed" \| "rendered" \| "failed" \| "finished" \| "clicked" \| "cancelled" \| "not_found"; payload?: any; }` | Fired when an action callback is triggered or changes status. |

### Share data lifecycle

| Event | Payload | Description |
| --- | --- | --- |
| `shareData.shareState` | `{ active: boolean }` | Fired when the data sharing state is updated. |
| `shareData.shareScreen` | `{ active: boolean }` | Fired when the screen sharing state is updated. |

## Match events with wildcards

Listen to multiple events at once using wildcard patterns.

| Pattern | Matches | Example |
| --- | --- | --- |
| `*` | All events | `foldspace.agent("demo").on("*", handler)` |
| `ui.*` | All UI lifecycle events | `foldspace.agent("demo").on("ui.*", handler)` |
| `conversation.*` | All conversation-related events | `foldspace.agent("demo").on("conversation.*", handler)` |

Listen to a group of events.

```javascript
foldspace.agent("demo").on("ui.*", (payload) => {
  console.log("UI event triggered:", payload);
});
```

Use `*` to listen to all events. The handler also receives the event name as a second argument.

```javascript
foldspace.agent("demo").on("*", (payload, eventName) => {
  console.log(`Event "${eventName}" fired with:`, payload);
});
```

## Remove listeners

To remove a specific listener, call `.off()` with the same event name and handler.

```javascript
const handler = (payload) => console.log("UI opened:", payload);

foldspace.agent("demo").on("ui.open", handler);

// Later...
foldspace.agent("demo").off("ui.open", handler);
```

If you used a wildcard (`*` or `group.*`), `.off()` removes the same handler for all matching events.

## Chain listeners

Chain listeners across lifecycle, UI, and conversation events.

```javascript
foldspace.agent("support")
  .on("agent.ready", () => console.log("Agent is ready"))
  .on("ui.open", ({ rect }) => console.log("Chat opened at:", rect))
  .on("conversation.created", ({ conversationId }) =>
    console.log("New conversation:", conversationId)
  );
```

## Related

- [Messaging API](/reference/messaging-api/): send messages to your agent.
- [Conversation API](/reference/conversation-api/): manage the conversations these events reference.