Supervisor IA

Agente assistente que ajuda usuários OWNER/MANAGER a entender, consultar e modificar configurações dos agentes via linguagem natural — com camada de aprovação humana para qualquer mudança real.

Como funciona

1. Você abre o widget flutuante no painel (canto inferior direito)
2. Pede algo: "Aumenta a temperatura do Carlos pra 0.9"
3. Supervisor consulta com get_agent, calcula o diff, e cria um PendingApproval
4. Você revê o diff (antes/depois) e aprova ou rejeita
5. Aprovado → executa de verdade. Rejeitado → não acontece nada.

Tudo é gravado: cada aprovação fica linkada à mensagem do chat que originou (via supervisorMessageId), permitindo histórico auditável.

Tools disponíveis

Inspeção (sem aprovação)

Tool	Uso
list_agents	Lista todos os agentes do workspace
get_agent	Detalhes completos (prompt, training, behavior)
find_agent_by_name	Busca por nome
list_intents	Intenções de um agente
list_webhooks	Webhooks de um agente
list_recent_conversations	Últimas N conversas (filtra por status)
get_conversation_messages	Histórico de uma conversa específica

Mutação (cria PendingApproval)

Tool	Cria approval para
propose_change com tool: update_agent_prompt	Editar prompt
propose_change com tool: update_agent_training	Editar training context
propose_change com tool: toggle_agent_active	Ativar/pausar
propose_change com tool: create_intent	Criar intent
propose_change com tool: update_intent	Editar intent
propose_change com tool: delete_intent	Deletar intent
propose_change com tool: create_webhook	Criar webhook
propose_change com tool: update_webhook	Editar webhook
propose_change com tool: delete_webhook	Deletar webhook

Endpoints

GET  /api/supervisor/conversation     # Recupera/cria conversa do workspace
POST /api/supervisor/chat             # Manda mensagem
DELETE /api/supervisor/conversation   # Reseta (apaga histórico)
GET  /api/supervisor/changes          # Lista approvals criados pelo supervisor

Aprovações

GET    /api/approvals?status=PENDING  # Lista pendentes
POST   /api/approvals/{id}/approve    # Aprovar (executa de fato)
POST   /api/approvals/{id}/reject     # Rejeitar

Aprovações expiram em 24h se ninguém aprovar/rejeitar — um cron job roda a cada 60s e marca como EXPIRED.

Custo

Cada mensagem do supervisor consome créditos:

custo_BRL = (input_tokens × $3 + output_tokens × $15 + cache_write × $3.75 + cache_read × $0.30) / 1M tokens
créditos = custo_BRL × 5 (USD→BRL) × 3 (markup) / 0.10

Mensagens típicas custam 0.20–0.50 créditos (~R$ 0.02–0.05). Use prompt caching (ativo por padrão) para reduzir.

Restrições

• Só OWNER e MANAGER acessam. AGENT/VIEWER recebem 403 Forbidden.
• 1 conversa por workspace (compartilhada entre OWNER/MANAGER).
• Histórico mantém últimas 30 mensagens em contexto; mensagens mais antigas ficam no DB mas não vão pro LLM.
• Tools de mutação sempre geram PendingApproval — supervisor nunca altera nada direto.