Quota mensal de tokens

Tokens IA são a "energia" que move os agentes. Cada mensagem que o agente recebe e responde consome tokens (cobertura do contexto da conversa + base de conhecimento + resposta gerada). Cada plano Syncro tem quota mensal de tokens — quando você esgota, agentes pausam automaticamente até o próximo ciclo (ou até você comprar pacote extra).

Esse artigo explica como funciona a quota, onde acompanhar uso e o que fazer quando esgotar.

O que é um "token"

Em LLMs (OpenAI, Anthropic, etc), texto é dividido em tokens — unidades aproximadas de:

• 1 palavra simples = ~1 token

• Palavra complexa ou estrangeira = 2-4 tokens

• 100 caracteres em português = ~30-40 tokens

• 1 mensagem média de WhatsApp (50 palavras) = ~80-100 tokens

Tanto a mensagem do cliente (input) quanto a resposta do agente (output) consomem tokens. Mas o maior consumo é o contexto que mandamos pro LLM — system prompt + base de conhecimento + histórico recente da conversa.

Quota por plano

Cada plano Syncro tem ai_tokens_monthly no features_json:

💡 Dica: 500k tokens cobre ~1000-1500 conversas curtas ou ~300-500 conversas longas com base de conhecimento robusta. Pra a maioria das operações pequenas, plano Starter é suficiente.

Como acompanhar uso

1. Acesse IA → Agentes (rota /ia/agentes).

2. Na sidebar lateral, há card Tokens de IA com:

• Uso do mês atual: número de tokens consumidos.

• % do limite: progresso visual.

• Limite mensal: tokens disponíveis no plano (base + incrementos).

• Gráfico — últimos 7 dias: barras mostrando consumo diário.

Estado: quota esgotada

Quando seu uso atinge 100% do limite:

• Agentes IA pausam automaticamente — não respondem mais.

• Modal de "Quota Esgotada" abre automaticamente em /ia/agentes.

• Modal mostra:

• Quota esgotada este mês ⚠️

• "Seu agente foi pausado automaticamente. Adicione mais tokens para reativá-lo."

• Lista de pacotes de tokens pra compra (ex: 100k, 500k, 1M tokens).

• Botão Comprar pacote selecionado.

O que acontece quando agente pausa

Com agente pausado:

• Mensagens novas chegam normalmente no /chats.

• Mas agente não responde — ficam acumulando.

• Cliente pode achar que você não tá atendendo (problema!).

Opções pra reativar:

1. Comprar pacote de tokens extra via PIX (modal). Veja Comprar pacotes.

2. Aguardar virar o mês — quota reseta no dia 1.

3. Atender manualmente com humanos enquanto isso.

Renovação mensal

A quota reseta automaticamente no dia 1 de cada mês:

• Cron interno do Syncro detecta novo mês.

• Calcula consumo do mês anterior (já registrado).

• Zera o contador pro mês corrente.

• Agentes voltam a funcionar.

⚠️ Atenção: tokens não acumulam entre meses. Se você não usou os 500k de outubro, eles expiram quando entra novembro. Não há "rollover".

Tokens de pacotes extras

Se você comprou pacotes extras (TenantTokenIncrement):

• Eles somam ao limite base do plano.

• Quando você consome, o sistema gasta tokens do limite total (não diferencia base vs extra).

• Pacotes extras só valem pro mês corrente — não acumulam pros próximos.

💡 Dica: comprou 100k extras quando faltavam 5 dias do mês? Use rapidinho. No dia 1 do próximo mês, zera tudo (extra inclusive) e volta pro limite base.

Como o consumo é calculado

Pra cada interação do agente:

1. Input tokens: contam tudo que entra no prompt do LLM:

• System prompt (persona, base de conhecimento, etapas, tools disponíveis).

• Histórico da conversa (últimas N mensagens).

• Mensagem atual do cliente.

• Chunks RAG (se houver).

2. Output tokens: contam a resposta do agente:

• reply textual.

• Tools chamadas (formato JSON).

3. Cada chamada ao LLM gera registro em ai_usage_logs:

• tokens_prompt (input)

• tokens_completion (output)

• tokens_total (soma)

• model (ex: gpt-4o-mini)

• created_at

4. Soma do mês vira o "uso atual" mostrado na sidebar.

Tokens consumidos na indexação (RAG)

Quando você sobe arquivo pra base de conhecimento:

• Sistema gera embeddings (OpenAI text-embedding-3-small).

• Esses tokens NÃO contam na quota mensal de chat.

• São registrados separadamente em ai_usage_logs com type='knowledge_indexing'.

Você pode subir arquivos sem se preocupar com quota.

Operações que CONSOMEM quota

Como reduzir consumo

Se você está consumindo muito:

1. Reduzir base de conhecimento textarea

Cada caractere no campo "Base de Conhecimento" vai no system prompt sempre. Se você tem 5000 chars, é overhead grande. Movimente conteúdo pra arquivos (RAG) — só os chunks relevantes vão.

2. Reduzir histórico considerado

Por padrão, agente vê últimas 10-15 mensagens. Pra conversas longas, isso é overhead. Ajuste se a UI permitir.

3. Limitar max_message_length

Configure pra resposta mais curta. 200 chars = menos tokens output que 4000.

4. Desativar agentes não usados

Se você tem 5 agentes ativos mas só 2 são usados, desative os 3 inativos. Eles não consomem quando inativos.

5. Usar followup_strategy=template

Templates HSM não consomem tokens — comportamento previsível e barato.

6. Usar chatbot em vez de IA pra fluxos simples

Pra qualificação inicial estruturada, chatbot tradicional (sem LLM) é mais barato. IA só pra perguntas abertas.

Métricas detalhadas (apenas via API/banco)

Pra análise mais profunda (consumo por agente, por canal, por dia):

• Hoje a UI não tem dashboard granular.

• Dados estão em ai_usage_logs no banco.

• Pode extrair via API REST v1 ou contate suporte.

Limites e edge cases

plano Trial não tem IA

plano Trial tem 0 tokens mensais. Agentes não funcionam. Pra testar IA, use Trial (14 dias com 50k tokens) ou Starter+.

Trial expira em 14 dias

Trial vira Free automaticamente após 14d. Tokens expiram junto — agentes param de funcionar.

Notificações de uso

Quando você bate 80% da quota:

• Sistema NÃO envia notificação automática ainda (em roadmap).

• Recomendação: monitore visualmente ou contate suporte pra alerta.

Quando bate 100%:

• Modal de quota esgotada abre.

• Pode ser configurado email automático no master (administradores Syncro).

Próximos passos

• Pra comprar pacotes extras, veja Comprar pacotes de tokens.

• Pra fazer upgrade do plano (mais tokens), veja Fazer upgrade.

Artigos relacionados

• Comprar pacotes de tokens

• Fazer upgrade de plano

• Criar agente IA