# Sinalizadores de recursos

Ative uma superfície do Beeuni em um projeto e saiba o que cada sinalizador controla.

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

Um sinalizador de recurso ativa uma superfície do Beeuni em um projeto. Qualquer superfície pode ser lançada atrás de um sinalizador — experimental, beta ou totalmente estável. "Experimental" é um selo de estabilidade de um sinalizador, não o nome do sistema.

Os sinalizadores são específicos de cada projeto. Ativar um sinalizador em um projeto não altera nada em outro projeto nem para outras contas.

- [Apps](/docs/pt/feature-flags/apps): Implante sites estáticos, bundles, Dockerfiles e imagens OCI em URLs estáveis.

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

## Ativar um sinalizador

1. Abra **Settings → Feature flags**. A guia lista todos os sinalizadores compatíveis com a plataforma.
2. Leia a linha: nome do sinalizador, selo de estabilidade, uma frase de descrição e a origem — `Default on`, `Default off` ou
   `Overridden for this project`.
3. Use o botão. A alteração é aplicada imediatamente ao projeto atual.

Você precisa da permissão `project.settings.write` do projeto. Para qualquer outra pessoa que fizer a chamada, a rota retorna
`403`.

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

### Pela CLI

Os mesmos controles estão disponíveis para scripts e agentes por meio de `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
```

Adicione `--project <id>` para agir em um projeto diferente do projeto vinculado ou padrão. Um sinalizador que a plataforma marca como indisponível permanece desativado, independentemente da configuração do projeto; a CLI exibe isso como `n/a` / `unavailable`.

> **O estado dos sinalizadores não fica no seu repositório**
>
> O estado dos sinalizadores por projeto fica no banco de dados, na linha do projeto. Ele nunca é lido de `beeuni.yaml`. Um sinalizador que você ativa não acompanha um clone ou fork do repositório.

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

## Selos de estabilidade

O selo descreve o contrato, não o controle. Um sinalizador `stable` ainda exige adesão explícita: `apps` é estável e continua desativado por padrão.

| Selo | Significado |
|---|---|
| Experimental | A superfície e seu contrato ainda podem mudar. |
| Beta | A superfície funciona e sua forma está se consolidando. |
| Stable | O contrato se mantém. O sinalizador continua opcional. |

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

## Como um sinalizador é aplicado

Cada sinalizador declara um modo de aplicação.

| Modo | O que o servidor faz quando o sinalizador está desativado |
|---|---|
| `routes` | A superfície HTTP rejeita a solicitação com `403`. |
| `behavioral` | O comportamento não ocorre — nenhum conector é materializado, nenhuma variável de ambiente é injetada e nenhum agente é registrado. |
| `ui-only` | O servidor deliberadamente não aplica o sinalizador. Ele oculta apenas a superfície do cliente. |

Uma rejeição `routes` é idêntica em todos os lugares:

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

A string `error` indica a lista de sinalizadores, não uma guia específica. A lista fica na guia **Experimental** de Settings.

Faça a verificação com `code`, nunca com o texto da mensagem. O SDK exporta `isFeatureDisabledError(error)` e `featureDisabledKey(error)` exatamente para isso.

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

## Todos os sinalizadores

Ordem do registro — a mesma exibida em **Settings → Feature flags**.

Apps são ativados por projeto pelo Beeuni. Entre em contato com o Beeuni para solicitar acesso. Após a ativação, Settings mostra **Managed by Beeuni**.

| Chave | Nome | Estabilidade | Padrão |
|---|---|---|---|
| `marketplace` | Marketplace | Beta | Ativado |
| `connectors_api_discover` | Connectors API Discover | Experimental | Desativado |
| `agentmail_email` | AgentMail Email | Experimental | Desativado |
| `llm_gateway` | LLM Gateway | Experimental | Ativado  |
| `meta_agent` | Meta Agent | Experimental | Desativado |
| `apps` | Apps | Stable | Desativado |
| `monitors` | Monitors | Experimental | Desativado |
| `reminders` | Reminders | Beta | Desativado |
| `warm_sessions` | Warm Sessions | Beta | Ativado |
| `secrets_egress` | Network-Enforced Secrets | Experimental | Ativado |
| `pi_harness` | Pi Harness  | Experimental | Desativado |

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

### O que cada sinalizador controla

- **`marketplace`** — pesquisar e instalar skills de registros da comunidade e de fornecedores.
- **`connectors_api_discover`** — pesquisar superfícies diretas de API, MCP, GraphQL, CLI e Postman ao lado de apps OAuth gerenciados. Consulte [Connectors](/docs/pt/connect/connectors).
- **`agentmail_email`** — atribuir conexões de caixa de entrada AgentMail para que emails recebidos iniciem e deem continuidade a sessões.
- **`llm_gateway`** — encaminhar o projeto pelo gateway LLM gerenciado do Beeuni. Consulte [Models](/docs/pt/project/models).
- **`meta_agent`** — adicionar um agente coordenador mantido pela plataforma, que inicia e gerencia sessões especializadas.
- **`apps`** — implantar sites estáticos, bundles, Dockerfiles e imagens OCI em URLs serverless estáveis. Consulte [Apps](/docs/pt/feature-flags/apps).
- **`monitors`** — executar monitores 24 horas por dia, 7 dias por semana, a partir do seu repositório, que disparam eventos de acionamento nas sessões. Consulte [Triggers](/docs/pt/connect/triggers).
- **`reminders`** — lembretes agendados que solicitam novamente uma sessão, uma vez ou repetidamente. Quando desativadas, as rotas de lembretes retornam `feature_disabled` e os lembretes existentes não são acionados. Consulte [Reminders](/docs/pt/connect/reminders).
- **`warm_sessions`** — manter um sandbox iniciado enquanto um projeto estiver aberto, para que uma nova sessão comece sem inicialização a frio.
- **`secrets_egress`** — oferecer aplicação de rede para um segredo: o sandbox mantém um identificador, e o Beeuni substitui o valor real apenas em solicitações a hosts aprovados. Consulte [Secrets](/docs/pt/project/secrets).
- **`pi_harness`** — executar as sessões deste projeto no harness de agente pi, dentro do sandbox de sessão comum (`BEEUNI_HARNESS=pi`). Ativado: toda sessão nova ou reiniciada inicia o pi, independentemente do que o manifesto especificar. Desativado: o manifesto decide — `runtime: pi` ainda inicia o pi; qualquer outra opção inicia o runtime padrão. O pi chama modelos apenas pelo gateway LLM: com `llm_gateway` desativado, todas as sessões iniciam o runtime padrão, independentemente deste sinalizador ou do manifesto. O layout do repositório, os agentes e as skills são os mesmos nas duas opções; uma sessão em execução mantém seu harness até ser reiniciada ou retomada. Os subagentes funcionam no pi: o agente delega com a ferramenta `task` para `general`, `explore` (somente leitura) ou qualquer agente do projeto com `mode: subagent` em seu `.md`, e a transcrição mostra no lugar certo as etapas de cada subagente. As sessões pi também carregam pacotes pi.dev: consulte [`harnesses:`](/docs/pt/project/manifest#harnesses). O pi não oferece todos os recursos de sessão que o runtime padrão oferece: consulte a matriz em [Harnesses](/docs/pt/work/harnesses#what-each-harness-supports).

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

### Sinalizadores que se tornaram padrão

Um recurso que se tornou padrão está ativado em todos os projetos e não tem controle.

- **Agentes como principais** é um comportamento padrão sem controle. Uma sessão de agente atua como o próprio agente — com as permissões Beeuni dentro dos limites de sua função, seja quem for que a execute. Consulte [Agent permissions](/docs/pt/project/permissions).
- **Review Center** saiu do sistema de sinalizadores. A página Review, a linha Review na barra lateral e a linha na paleta de comandos aparecem em todos os projetos; as permissões `project.review.read` e `project.review.act` continuam se aplicando. `review_center` não é mais uma chave de sinalizador: `PATCH /v1/projects/:id/features` retorna `400` `Unknown feature flag`, e `beeuni projects features enable review_center` prints that error and exits `1`. Uma substituição armazenada de antes dessa mudança não tem efeito.
- **Computers** saiu do sistema de sinalizadores. Todos os membros podem conectar seu próprio computador pela barra lateral do projeto; a configuração `TUNNEL_ENABLED` da plataforma é o único controle. `agent_tunnel` não é mais uma chave de sinalizador: `PATCH /v1/projects/:id/features` retorna `400` `Unknown feature flag`. Consulte [Computers](/docs/pt/connect/computers).
- **Microsoft Teams** saiu do sistema de sinalizadores. Todos os projetos podem conectar o Teams em **Connectors → Channels**; um administrador do locatário ainda precisa autorizar uma vez, ou o projeto pode trazer seu próprio bot. `teams` não é mais uma chave de sinalizador: `PATCH /v1/projects/:id/features` retorna `400` `Unknown feature flag`. Uma substituição armazenada de antes dessa mudança não tem efeito. Consulte [Microsoft Teams](/docs/pt/connect/teams).

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

## Efeitos colaterais de um controle

Alguns sinalizadores fazem o estado da plataforma convergir depois que a gravação é confirmada.

| Sinalizador | Efeito após a alteração |
|---|---|
| `agentmail_email` | O Beeuni executa novamente a materialização do conector de canal, para que o conector apareça ou desapareça com o sinalizador. |
| `llm_gateway` | O Beeuni propaga o novo modo de provedor para os sandboxes ativos. |

Os efeitos são tarefas de convergência, não fazem parte do sucesso da alteração. A resposta da API não espera que sejam concluídas. Cada efeito é repetido uma vez, e os reconciliadores responsáveis são idempotentes e executados novamente em suas verificações periódicas.

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

## Ler e definir um sinalizador no código

Leia o estado efetivo por projeto nos detalhes do projeto ou pelo hook do 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` será `true` somente quando o servidor tiver respondido exatamente `true`. Um ID de projeto ausente, uma consulta em andamento ou um erro resultam em `false`. Em caso de dúvida, bloqueie o acesso.

Defina a substituição do projeto com o cliente:

```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` chama `PATCH /v1/projects/:id/features`. `feature` é uma das opções `FEATURE_FLAG_KEYS`, exportadas de `@beeuni/sdk` e tipadas como `FeatureFlagKey`. Consulte a referência do SDK.

Trate um recurso desativado pelo código, não pela mensagem:

```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`);
  }
}
```