---
audience: everyone
summary: How AI participants join rooms, when they respond, and what knobs you can
  turn.
title: AI engagement
path: concepts/ai-engagement
status: published
---

# AI engagement

The mental model: an AI is a room member that you can `@mention`, give
a power level, kick, redact, and instruct. What makes it different
from a human member is *when it speaks* and *how much agency you give
it*. Those are the engagement settings.

## Engagement modes

A room's **engagement mode** controls when the AI speaks
spontaneously:

| Mode | Behaviour |
|---|---|
| `always` (default for new rooms) | After every human message. |
| `mention` | Only when an `@<ai-name>` appears in a new message. |
| `keyword` | When a configured keyword matches the message body. |
| `autonomous` | For sidekick agents — the AI drives its own turns until the task completes. |

> **What happens when you invite an AI to a new room.** Group rooms
> seed `always` by default; 1-on-1 rooms (DM with AI, sidekick,
> AI session) always seed `always` regardless of preference.
> Change the group-room default for your account under **Settings →
> AI → When you invite an AI to a new group room**.

Change a single room's mode any time with
`PUT /v1/rooms/{room_id}/ai/engagement` or via the **Engagement**
menu in the chat header.

## Response modes

How the AI's reply lands in the timeline:

- **`streaming`** — tokens arrive live, building one message in place.
  Best for short replies and code blocks. The whole reply lives as a
  single message in the timeline.
- **`conversational`** — the AI's reply is buffered and flushed as
  separate messages on paragraph boundaries. Best for long-form
  replies; feels like a person typing follow-ups.

Response mode is per-`(room × AI)` so a single room with two AIs can
have them on different modes. Change via the toggle in the chat header
or with `PUT /v1/rooms/{room_id}/ai/response-mode`.

## System prompt overrides

Every AI has a default system prompt configured by an admin. In a
specific room you can override it with `PUT /v1/rooms/{room_id}/ai/system-prompt`
or by editing the **System** field under **Engagement → Settings**.
The override is *additive*: room-level instructions are appended to
the AI's base prompt for that room only.

A common pattern is a base "you are a friendly assistant" prompt plus a
room-level "you are debugging a payment integration; assume Stripe
context" override.

## Plugins

The AI can call **plugins** to do work it can't do with words alone.
The standard set is:

- `web_search` — query the live web (SearXNG-backed).
- `web` — fetch a specific URL.
- `scaiwave.notes` — find, read, create, update notes.
- `scaiwave.todos` — manage cross-workspace todos.
- `scaiwave.drive` — search ScaiDrive (file storage).
- `scaiwave.knowledge` — RAG against tenant-private knowledge.
- `scaiwave.calculator` — exact arithmetic.
- `scaiwave.calendar` — calendar lookups.
- `scaiwave.memory` — long-term memory across conversations.
- `scaiwave.scailink` — delegate to specialist tools registered by
  other ScaiLabs services.
- `scaiwave.workspace_bridge` — write into a workspace-bridged
  external service.
- `scaiwave.skills` — skill library invocation.

Each plugin is enabled or disabled per-tenant by an admin. Per-room
overrides are possible (`POST /v1/rooms/{room_id}/plugins/{plugin_id}/toggle`).

The AI sees plugin tools in its function-calling schema; it decides
when to use them based on the question. The harness rules around
how the AI handles tool failures (e.g. trying a fallback before
giving up) live in the [planner](/docs/scaiwave/concepts/planner)
and tool-etiquette system prompt.

## Sampling parameters

Per AI: `temperature`, `top_p`, `max_tokens`, `frequency_penalty`,
`presence_penalty`, and (for reasoning models) `reasoning_effort`.
Tune from **Engagement → Sampling** or via the API at
`PUT /v1/rooms/{room_id}/ai/temperature` etc. Per-room overrides
stack on top of the AI's defaults; the prompt studio shows you
exactly what's being sent.

## Stopping an AI mid-response

- Click **Stop** in the chat header.
- Send another message — engagement cancels the in-flight generation.
- `POST /v1/rooms/{room_id}/ai/stop`.

## Where to go next

- [Sidekicks](/docs/scaiwave/concepts/sidekicks) — delegate long tasks.
- [Planner](/docs/scaiwave/concepts/planner) — multi-step plans.
- [Plugins and tools](/docs/scaiwave/concepts/plugins-and-tools) — the AI's toolbox.
- Tutorial: [Tune AI response mode](/docs/scaiwave/tutorials/power-user/tune-ai-response-mode).
- Tutorial: [Use the prompt studio](/docs/scaiwave/tutorials/power-user/use-prompt-studio).
- API: [AI](/docs/scaiwave/reference/api/ai).