# Flag delle funzionalità

Attiva una superficie Beeuni per un progetto e scopri cosa controlla ogni flag.

Canonical page: https://beeuni.ai/docs/it/feature-flags

Un flag delle funzionalità attiva una superficie Beeuni per un progetto. Qualsiasi superficie può essere distribuita dietro un flag — sperimentale, beta o completamente stabile. «Sperimentale» è un badge di stabilità associato a un flag, non il nome del sistema.

I flag sono specifici per progetto. Attivare un flag in un progetto non cambia nulla in un altro progetto né per altri account.

- [Apps](/docs/it/feature-flags/apps): Distribuisci siti statici, bundle, Dockerfile e immagini OCI su URL stabili.

<a id="turn-a-flag-on"></a>

## Attivare un flag

1. Apri **Settings → Feature flags**. La scheda elenca tutti i flag supportati dalla piattaforma.
2. Leggi la riga: nome del flag, badge di stabilità, descrizione di una frase e origine — `Default on`, `Default off` o
   `Overridden for this project`.
3. Usa l’interruttore. La modifica si applica immediatamente al progetto corrente.

Ti serve l’autorizzazione `project.settings.write` del progetto. La route risponde con
`403` per qualsiasi altro chiamante.

<a id="from-the-cli"></a>

### Dalla CLI

Gli stessi interruttori sono disponibili per script e agenti tramite `beeuni projects features`:

```bash
beeuni projects features                # every flag: key, state, origin
beeuni projects features enable reminders
beeuni projects features disable reminders
beeuni projects features reset reminders  # drop the override; follow the platform default
beeuni projects features --json          # the full catalog as JSON
```

Aggiungi `--project <id>` per intervenire su un progetto diverso da quello collegato o predefinito. Un flag che la piattaforma segna come non disponibile resta disattivato, qualunque sia l’impostazione del progetto; la CLI lo mostra come `n/a` / `unavailable`.

> **Lo stato dei flag non è nel tuo repo**
>
> Lo stato dei flag per progetto risiede nel database, nella riga del progetto. Non viene mai letto da `beeuni.yaml`. Un flag che attivi non viene trasferito con la clonazione o la biforcazione di un repository.

<a id="stability-badges"></a>

## Badge di stabilità

Il badge descrive il contratto, non l’interruttore. Un flag `stable` richiede comunque l’attivazione esplicita: `apps` è stabile e resta disattivato per impostazione predefinita.

| Badge | Significato |
|---|---|
| Sperimentale | La superficie e il relativo contratto possono ancora cambiare. |
| Beta | La superficie funziona e la sua forma si sta consolidando. |
| Stabile | Il contratto è garantito. Il flag richiede comunque l’attivazione esplicita. |

<a id="how-a-flag-is-enforced"></a>

## Applicazione di un flag

Ogni flag dichiara una modalità di applicazione.

| Modalità | Cosa fa il server quando il flag è disattivato |
|---|---|
| `routes` | La superficie HTTP rifiuta la richiesta con `403`. |
| `behavioral` | Il comportamento non si verifica: nessun connettore viene materializzato, nessun env viene iniettato, nessun agente viene registrato. |
| `ui-only` | Il server non applica deliberatamente alcun vincolo. Il flag nasconde solo la superficie client. |

Un rifiuto `routes` è identico ovunque:

```json
{
  "error": "Apps is not enabled for this project. Contact Beeuni to enable it.",
  "code": "feature_disabled",
  "feature": "apps"
}
```

La stringa `error` indica l’elenco dei flag, non una scheda specifica. L’elenco si trova nella scheda **Experimental** delle impostazioni.

Usa `code` per diramare il codice, mai il testo del messaggio. L’SDK esporta `isFeatureDisabledError(error)` e `featureDisabledKey(error)` proprio a questo scopo.

<a id="every-flag"></a>

## Tutti i flag

Ordine del registro — lo stesso mostrato in **Settings → Feature flags**.

Beeuni attiva Apps per progetto. Contatta Beeuni per richiedere l’accesso. Dopo l’attivazione, Settings mostra **Managed by Beeuni**.

| Chiave | Nome | Stabilità | Predefinito |
|---|---|---|---|
| `marketplace` | Marketplace | Beta | Attivo |
| `connectors_api_discover` | Connectors API Discover | Sperimentale | Disattivato |
| `agentmail_email` | AgentMail Email | Sperimentale | Disattivato |
| `llm_gateway` | LLM Gateway | Sperimentale | Attivo  |
| `meta_agent` | Meta Agent | Sperimentale | Disattivato |
| `apps` | Apps | Stabile | Disattivato |
| `monitors` | Monitors | Sperimentale | Disattivato |
| `reminders` | Reminders | Beta | Disattivato |
| `warm_sessions` | Warm Sessions | Beta | Attivo |
| `secrets_egress` | Network-Enforced Secrets | Sperimentale | Attivo |
| `pi_harness` | Pi Harness  | Sperimentale | Disattivato |

<a id="what-each-flag-gates"></a>

### Cosa controlla ogni flag

- **`marketplace`** — esplora e installa skill dai registri della community e dei fornitori.
- **`connectors_api_discover`** — esplora le superfici API dirette, MCP, GraphQL, CLI e Postman, oltre alle app OAuth gestite. Vedi [Connettori](/docs/it/connect/connectors).
- **`agentmail_email`** — assegna connessioni alle caselle di posta di AgentMail, così le email in arrivo avviano e proseguono le sessioni.
- **`llm_gateway`** — instrada il progetto tramite il gateway LLM gestito di Beeuni. Vedi [Modelli](/docs/it/project/models).
- **`meta_agent`** — aggiungi un agente coordinatore gestito dalla piattaforma, che avvia e gestisce sessioni specializzate.
- **`apps`** — distribuisci siti statici, bundle, Dockerfile e immagini OCI su URL serverless stabili. Vedi [App](/docs/it/feature-flags/apps).
- **`monitors`** — esegui watcher attivi 24/7 dal tuo repository, che inviano eventi trigger alle sessioni. Vedi [Trigger](/docs/it/connect/triggers).
- **`reminders`** — controlli pianificati che inviano di nuovo un prompt a una sessione, una volta o a intervalli regolari. Se disattivata, la route dei promemoria risponde `feature_disabled` e i promemoria esistenti non vengono attivati. Vedi [Promemoria](/docs/it/connect/reminders).
- **`warm_sessions`** — mantieni un sandbox avviato mentre un progetto è aperto, così una nuova sessione parte senza un avvio a freddo.
- **`secrets_egress`** — applica il controllo di rete a un segreto: il sandbox conserva un handle e Beeuni sostituisce il valore reale solo nelle richieste agli host approvati. Vedi [Segreti](/docs/it/project/secrets).
- **`pi_harness`** — esegui le sessioni di questo progetto sull'harness dell'agente pi all'interno del normale sandbox di sessione (`BEEUNI_HARNESS=pi`). Attivata: ogni nuova sessione o sessione riavviata avvia pi, indipendentemente da quanto indica il manifest. Disattivata: decide il manifest — `runtime: pi` avvia comunque pi, qualsiasi altro valore avvia il runtime predefinito. pi chiama i modelli solo tramite il gateway LLM: con `llm_gateway` disattivata, ogni sessione avvia il runtime predefinito, indipendentemente da questo flag o dal manifest. In entrambi i casi, layout del repository, agenti e skill sono gli stessi; una sessione in corso mantiene il proprio harness finché non viene riavviata o ripresa. I subagenti funzionano su pi: l'agente delega con lo strumento `task` a `general`, `explore` (sola lettura) o a qualsiasi agente del progetto con `mode: subagent` nel suo `.md`, e la trascrizione mostra in ordine i passaggi di ogni subagente. Le sessioni pi caricano anche i pacchetti pi.dev: vedi [`harnesses:`](/docs/it/project/manifest#harnesses). pi non supporta tutte le funzionalità di sessione del runtime predefinito: consulta la matrice in [Harness](/docs/it/work/harnesses#what-each-harness-supports).

<a id="graduated-flags"></a>

### Flag resi permanenti

Una funzionalità resa permanente è attiva per ogni progetto e non ha un interruttore.

- **Agenti come entità principali** è il comportamento standard e non ha interruttori. Una sessione dell'agente opera come l'agente stesso, con le autorizzazioni Beeuni entro i limiti del suo ruolo, indipendentemente da chi la avvia. Vedi [Autorizzazioni degli agenti](/docs/it/project/permissions).
- **Review Center** è uscito dal sistema dei flag. La pagina Review, la voce Review nella barra laterale e la voce nel menu dei comandi sono visibili per ogni progetto; restano valide le autorizzazioni `project.review.read` e `project.review.act`.
  `review_center` non è più una chiave flag: `PATCH /v1/projects/:id/features` risponde `400` `Unknown feature flag`, e `beeuni projects features enable
  review_center` prints that error and exits `1`. Un override salvato prima che la funzionalità diventasse permanente non ha effetto.
- **Computers** è uscito dal sistema dei flag. Ogni membro può connettere il proprio computer dalla barra laterale del progetto; l'unico requisito è l'impostazione della piattaforma `TUNNEL_ENABLED`. `agent_tunnel` non è più una chiave flag: `PATCH /v1/projects/:id/features` risponde `400` `Unknown feature flag`.
  Vedi [Computer](/docs/it/connect/computers).
- **Microsoft Teams** è uscito dal sistema dei flag. Ogni progetto può connettere Teams da **Connettori → Canali**; un amministratore del tenant deve comunque concedere il consenso una volta, oppure il progetto può usare il proprio bot. `teams` non è più una chiave flag: `PATCH /v1/projects/:id/features` risponde `400` `Unknown feature flag`. Un override salvato prima che la funzionalità diventasse permanente non ha effetto. Vedi [Microsoft Teams](/docs/it/connect/teams).

<a id="side-effects-of-a-toggle"></a>

## Effetti collaterali di un interruttore

Alcuni flag convergono lo stato della piattaforma dopo il commit della scrittura.

| Flag | Effetto dopo l'attivazione o la disattivazione |
|---|---|
| `agentmail_email` | Beeuni riesegue la materializzazione del connettore di canale, che appare o scompare in base al flag. |
| `llm_gateway` | Beeuni propaga la nuova modalità del provider ai sandbox attivi. |

Gli effetti sono operazioni di convergenza, non fanno parte dell'esito positivo dell'interruttore. La risposta API non li attende. Ogni effetto viene ritentato una volta e i processi di riconciliazione che lo gestiscono sono idempotenti e vengono rieseguiti nei rispettivi cicli periodici.

<a id="read-and-set-a-flag-from-code"></a>

## Leggere e impostare un flag dal codice

Leggi lo stato effettivo per progetto tramite i dettagli del progetto o l'hook React:

```tsx
import { useFeatureFlag } from '@beeuni/sdk/react';

function AppsNavItem({ projectId }: { projectId: string }) {
  const apps = useFeatureFlag(projectId, 'apps');
  if (!apps.enabled) return null;
  return <Link href={`/projects/${projectId}/apps`}>Apps</Link>;
}
```

`enabled` è `true` solo quando il server ha restituito esattamente `true`. Un ID progetto mancante, una query in corso e un errore restituiscono tutti `false`. In caso di dubbio, nega l'accesso.

Imposta l'override del progetto con il client:

```ts
const p = beeuni.project(projectId);

await p.updateFeatureFlag('apps', true);   // turn it on for this project
await p.updateFeatureFlag('apps', null);   // clear the override, inherit the default
```

`updateFeatureFlag` chiama `PATCH /v1/projects/:id/features`. `feature` è uno dei valori di `FEATURE_FLAG_KEYS`, esportato da `@beeuni/sdk` e tipizzato come `FeatureFlagKey`. Vedi il riferimento dell'SDK.

Gestisci una funzionalità disattivata nel codice, non in base al messaggio:

```ts
import { featureDisabledKey, isFeatureDisabledError } from '@beeuni/sdk';

try {
  await beeuni.project(projectId).apps.list();
} catch (error) {
  if (isFeatureDisabledError(error)) {
    console.log(`${featureDisabledKey(error)} is off for this project`);
  }
}
```