Projetos & Workspaces
Todo recurso no SipPulse AI — agentes, bases de conhecimento, chaves API, threads, análises estruturadas — pertence a um Projeto. Projetos são a principal forma de organizar seu trabalho, controlar acessos e gerenciar orçamentos em sua organização.
O que é um Projeto?
Um Projeto é um workspace isolado que agrupa recursos relacionados. Pense nele como uma pasta para tudo que está relacionado a uma iniciativa, cliente ou equipe específica.
Exemplos de projetos:
- "Suporte ao Cliente" — agentes e bases de conhecimento para sua equipe de suporte
- "Vendas Outbound" — agentes de voz e analytics para chamadas de vendas
- "Ferramentas Internas" — integrações de API e análises estruturadas para uso interno
Workspace Padrão
Quando sua organização é criada, um Workspace Padrão é configurado automaticamente. Todos os recursos pré-existentes (agentes, bases de conhecimento, chaves API, etc.) são atribuídos a este workspace.
Você pode renomear o Workspace Padrão e personalizá-lo como qualquer outro projeto, mas ele não pode ser excluído.
TIP
Se sua equipe trabalha em uma única iniciativa, o Workspace Padrão pode ser tudo que você precisa. Crie projetos adicionais apenas quando precisar de separação clara entre diferentes cargas de trabalho.
Criando um Projeto
- Navegue até Projetos no menu lateral
- Clique em Criar Projeto
- Preencha os detalhes:
- Nome: Um nome descritivo para o projeto
- Ícone: Escolha entre os ícones disponíveis para identificar visualmente o projeto
- Cor: Selecione uma cor que aparecerá no Project Switcher e em toda a interface
- Clique em Salvar
Project Switcher
O Project Switcher está localizado no menu lateral e permite alternar rapidamente entre projetos. Quando você seleciona um projeto, toda a plataforma filtra para mostrar apenas os recursos pertencentes àquele projeto.
- Todas as páginas (Agentes, Base de Conhecimento, Chaves API, Dashboard, etc.) respeitam o projeto selecionado
- Criar um novo recurso automaticamente o atribui ao projeto ativo
- O Project Switcher exibe o ícone e a cor do projeto para identificação rápida
Recursos Pertencem a Projetos
Os seguintes recursos são vinculados ao projeto ativo:
| Recurso | O que significa |
|---|---|
| Agentes | Cada agente pertence a um projeto. Você pode copiar agentes para outros projetos. |
| Bases de Conhecimento | Tabelas e seus dados são vinculados ao projeto. |
| Chaves API | Cada chave é vinculada a um projeto e só pode acessar recursos daquele projeto. |
| Threads | Conversas são associadas ao projeto do agente que as criou. |
| Análises Estruturadas | Esquemas de análise pertencem a um projeto. |
| Webhooks | Configurações de webhooks são vinculadas ao projeto. |
Membros Org-Scope vs Project-Scope
Como um membro da equipe interage com projetos depende do escopo do seu papel:
Papéis Org-Scope (Admin, Member)
- Veem todos os projetos no Project Switcher — sem restrições
- Não estão sujeitos a orçamentos de projeto — seu uso é rastreado no nível da organização
- Podem gerenciar recursos em qualquer projeto
- Visibilidade completa do menu lateral (baseada nas permissões do papel)
Papéis Project-Scope (Developer, Viewer)
- Veem apenas projetos atribuídos — precisam ser explicitamente adicionados a cada projeto que necessitam acessar
- Estão sujeitos a orçamentos de projeto — seu uso conta contra os limites de orçamento do projeto
- Só podem interagir com recursos em seus projetos atribuídos
- Visibilidade reduzida do menu lateral baseada em permissões
Exemplo Prático
Um Admin pode alternar entre todos os projetos e gerenciar tudo. Um Developer atribuído a "Suporte ao Cliente" e "Vendas Outbound" verá apenas esses dois projetos no Project Switcher, e não poderá acessar "Ferramentas Internas".
Personalização
Cada projeto pode ser personalizado com:
- Ícone: Identificador visual exibido no Project Switcher e nos cabeçalhos do projeto
- Cor: Cor de destaque usada em toda a interface quando o projeto está ativo
Isso ajuda as equipes a distinguir rapidamente entre projetos, especialmente quando alternam frequentemente.
Orçamento por Projeto
Usuários org-scope (Owner e Admin) podem configurar orçamentos de gastos para projetos individuais para controlar custos. A configuração de orçamento é acessada pelo botão Configurações de Orçamento (ícone de carteira) na tabela de projetos. Usuários project-scope não podem configurar orçamentos — apenas visualizam o status do orçamento.
Janelas de Tempo
Orçamentos usam um sistema de janelas de tempo com duas janelas independentes:
| Janela | Padrão | Propósito |
|---|---|---|
| Janela curta | 5 horas | Prevenir picos súbitos de custo (ex: um agente descontrolado) |
| Janela longa | 7 dias | Controlar gastos gerais do projeto em um período mais longo |
Cada janela rastreia gastos de forma independente. As janelas começam a contar a partir da primeira operação faturável e reiniciam automaticamente quando expiram — nenhuma intervenção manual necessária.
Como Orçamentos Funcionam
- Limites de orçamento são definidos na moeda da sua organização
- Membros project-scope (Project Manager, Developer, Member, Viewer) veem o orçamento apenas como percentuais — sem valores em dinheiro
- Membros org-scope (Owner, Admin) veem detalhes completos incluindo valores, saldo restante e horários de reset
- Um Indicador de Orçamento aparece no cabeçalho da página quando um projeto tem orçamento configurado, mostrando mini barras de progresso para cada janela ativa
- Abrir o indicador mostra a composição do uso de cada janela: quais tipos de cobrança consumiram a janela e quais modelos dentro de cada tipo. Cada fatia é um percentual, em duas leituras lado a lado — a participação dela no consumo e a parcela aproximada do orçamento que ela representa. Consumo sem modelo identificado aparece como "Não identificado", e as menores fatias são agrupadas em "Outros"
- Uso cobrado na sua própria chave de provedor (BYOK) não tem custo para o orçamento, então fica fora dos percentuais — a composição avisa quando esse uso existe
- Na tabela de projetos, a coluna Uso mostra o consumo do orçamento de relance com barras codificadas por cor (verde → âmbar → laranja → vermelho)
Quando o Orçamento é Excedido
Quando o orçamento de um projeto é excedido em qualquer janela:
- Novas operações faturáveis (chamadas LLM, transcrições, TTS) são bloqueadas para aquele projeto
- O Indicador de Orçamento fica vermelho com um alerta "Orçamento excedido"
- Chamadas de API retornam erro 429 com o tempo restante até o reset da janela
- Recursos existentes permanecem acessíveis — apenas novas operações faturáveis são bloqueadas
Configuração de Orçamento
| Configuração | Descrição |
|---|---|
| Horas da janela curta | Duração da janela curta (padrão: 5h, mín: 1h) |
| Limite da janela curta | Gasto máximo na janela curta (na sua moeda) |
| Dias da janela longa | Duração da janela longa (padrão: 7d, mín: 1d) |
| Limite da janela longa | Gasto máximo na janela longa (na sua moeda) |
| Aplicar limite | Se deve bloquear operações quando excedido, ou apenas rastrear uso |
| Aplicar para org-scope | Se Owner e Admin também estão sujeitos ao orçamento (padrão: desligado — eles não são afetados) |
| Contabilizar uso org-scope | Se o uso de Owner e Admin conta no orçamento do projeto (padrão: desligado) |
Cada janela pode ser habilitada ou desabilitada independentemente. Deixar o limite vazio desabilita aquela janela.
Alertas de Orçamento
Você pode configurar notificações por email para cada janela de tempo independentemente:
- Habilite o limite de orçamento para uma janela (curta ou longa)
- Ative o Alerta por Email nas configurações daquela janela
- Defina o Limite de Alerta — o percentual em que a notificação é disparada (ex: 80%)
- Escolha quais papéis devem receber o email de alerta
Por padrão, Owner, Admin e Project Manager recebem as notificações. Você pode personalizar isso por projeto no modal de configuração de orçamento.
TIP
Defina thresholds diferentes para as janelas curta e longa. Um threshold mais baixo na janela curta (ex: 70%) dá mais tempo à sua equipe para reagir a picos súbitos de gastos.
Removendo um Orçamento
Para remover o orçamento de um projeto e reverter para gastos ilimitados, exclua a configuração de orçamento no modal de configurações de orçamento.
Gerenciando Projetos
| Ação | Quem pode fazer |
|---|---|
| Criar um projeto | Admin |
| Editar detalhes do projeto | Admin |
| Arquivar um projeto | Admin |
| Adicionar membros a um projeto | Admin |
| Alternar entre projetos | Qualquer um (dentro dos projetos visíveis) |
Para uma análise completa do que cada papel pode fazer, veja Papéis & Permissões.
Próximos Passos
- Papéis & Permissões — Entenda o que cada papel da equipe pode acessar
- Gestão de Equipe — Adicione membros e atribua-os a projetos
- Plano & Assinatura — Configure orçamentos e limites de recursos