## Overview

**Maestro** is the platform's AI engine: it powers the account Brain, the copilot, the agents and
generative onboarding. The integration is managed by the operator in the admin console — no
redeploy needed to change configuration.

## Prerequisites

- Access to the operator console (Super Admin).
- The Maestro service's internal URL and the admin key provided at deployment.

## Step by step

1. Open the operator console → Maestro settings.
2. Fill in the **API URL** (internal address) and, if applicable, the **Public URL** (used for
   agent webhooks).
3. Enter the **admin key** — it is masked and never displayed again.
4. Choose the **onboarding mode** for new accounts: off, guided (wizard) or automatic.
5. Set the **default vertical template** applied when signup carries no segment.
6. Save and use **"Test connection"** to validate.

## Settings & options

- **Maestro enabled**: master switch. When off, every AI surface answers with a clear
  "disabled by the operator" state instead of connection errors.
- **Allow account keys (BYOK)**: controls whether accounts may use their own AI keys (see
  "AI tokens per account").
- Panel configuration takes precedence over environment variables; environments provisioned via
  variables keep working.

### Human-attendance pause

When a conversation is assumed or assigned to a person, its pause state is stored durably and remains
valid after restarting the API, workers or cache. Resume releases the agent only after a valid
confirmation; an unknown state is treated as paused.

Each agent also controls what to retain from inbound messages received during the pause: **discard**
(default), keep only the **latest**, or keep a **bounded set** by count and age. Resuming never replays
those messages by itself. Replay is a separate, explicit operator-confirmed action.

To process a retained queue safely:

1. Remove the human assignee from the conversation if one is still assigned.
2. In the conversation's **Maestro** panel, select **Resume** and wait for confirmation. This action
   releases only new messages.
3. The **Messages received during the pause** card appears only after Resume is confirmed.
4. Select **Process retained messages**, review the impact and choose **Confirm processing**.

Each attempt uses a unique retry-safe identifier: if the network response is lost, trying again does
not process the same queue twice. Without confirmation, with an unknown state or while a human remains
assigned, the platform keeps the queue blocked.

## Use cases

- Rotate the admin key after a credential rotation without restarting services.
- Enable automatic onboarding only after validating the guided flow on pilot accounts.

## Tips, limits & best practices

- Rotate the admin key periodically and after any suspected exposure.
- Keep the internal URL reachable only on the private network; expose only the public URL.

## Troubleshooting

The diagnostics panel shows one of five states:

- **OK**: service reachable and authenticated.
- **Authentication failed**: the admin key doesn't match the service's — update one of the sides.
- **Unreachable**: the URL doesn't respond (DNS, network, stopped service). The detail shows why.
- **Disabled**: the "Maestro enabled" master switch is off.
- **Not configured**: the admin key is missing.

While the service is **Unreachable** or returns an invalid state, automatic replies, effectful tools
and Follow-ups configured to honor human attendance remain blocked until the state is known again.

If generative onboarding is active and Maestro is unavailable, accounts keep being provisioned with
the vertical templates — nothing gets blocked.

## See also

- AI tokens per account (BYOK)
- Usage and consumption limits
- AI onboarding