Sinalizadores de recursos

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

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.

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.

Pela CLI

Os mesmos controles estão disponíveis para scripts e agentes por meio de beeuni projects features:

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.

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.

Como um sinalizador é aplicado

Cada sinalizador declara um modo de aplicação.

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

{
  "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.

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.

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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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:. O pi não oferece todos os recursos de sessão que o runtime padrão oferece: consulte a matriz em Harnesses.

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.
• 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.
• 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.

Efeitos colaterais de um controle

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

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.

Ler e definir um sinalizador no código

Leia o estado efetivo por projeto nos detalhes do projeto ou pelo hook do React:

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:

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:

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