Agentes IA

Status: 🟡 Em fluxo (modo rascunho — auto_respond=false por default) Code: backend/app/modules/agents UI: frontend/src/app/(admin)/[slug]/admin/agents Última revisão deste doc: 2026-05-13 por Felipe + Claude Dependências fortes: whatsapp + instagram (canais), council (recebe ações via bridge), business (brand_voice, knowledge, products), tenant_router

1. Identidade

O que faz (uma frase)

Provisiona, configura e executa agentes de IA externos (Hari, Clara, Aurora, Chandra, Dunning, etc.) que conversam com o cliente final via WhatsApp (DM + grupos), Instagram (DM + comentários) e email — sempre dentro do tom da marca, com escopo limitado e auditoria completa.

Por que existe (negócio)

Mandir tem duas IAs separadas (memória [[camadas_ia]]):

• Conselho = gerência (fala com Felipe, vê tudo).
• Agentes = operação (falam com cliente, escopo restrito).

Sem agentes externos, atendimento depende de Felipe online 24/7. Com agentes, Mais Consciente:

• Responde lead em <30s mesmo às 3h da manhã.
• Faz onboarding consistente (sem variar tom).
• Cobra inadimplente sem desgaste pessoal.
• Modera comunidade WhatsApp respeitando regras.
• Responde comentários públicos no Instagram com prudência.

Agentes são "papéis" personalizáveis — manager, vendedor, agendamento, suporte, conteúdo, dunning, community_moderator, onboarding, student_mirror, low_ticket_sales — cada tenant escolhe quais ativar.

Por que existe (técnico)

A separação Agentes/Conselho não pode ser código compartilhado porque:

1. Escopo distinto — Conselho vê billing + intelligence; Agente vê só catálogo + brand_voice + histórico do contato.
2. Riscos diferentes — Conselho pode propor ações (humano aprova); Agente envia em tempo real (precisa kill switch + fallback humano explícito).
3. Multi-instância — agentes ficam vinculados a whatsapp_provider_account ou instagram_account específicos.
4. Modos de roteamento — agents_instance_mode controla se DM cai pro Manager (orquestrador), agente dedicado, ou pool de time.
5. Auto-rollback de prompt drift — proposta de mudança de persona pode ser revertida automaticamente se score cair (Fase 10x — sub-feature avançada).

Como módulo dedicado:

• Slugs estáveis (agentes são nomes, não funções — memória [[agentes-nomes-nao-funcoes]]).
• Templates pré-configurados (9 templates: manager + 8 especialistas).
• Brain isolado com tools read-only restritas (sem propose_action que o Conselho tem).
• Telemetria por run + scoring multi-axis (knowledge, welcoming, conversion, compliance).

Status atual

• 6 agentes seeded em prod no Mais Consciente (manager, onboarding, dunning, student_mirror, community_moderator, low_ticket_sales) — memória [[agentes-preenchidos-2026-05-13]]. Todos com auto_respond=false (modo rascunho).
• Hub.7 deployado (2026-05-13) — DM IG → agente em prod (commit 4db4beb, alembic 0108). Memória [[hub-7-instagram-dm-agente-deployed]].
• Hub.8 deployado (2026-05-13) — Comments IG → agente em prod (commit d6af3dd, alembic 0110). Memória [[hub-8-ig-comments-agente-deployed]].
• Hub.7.1 deployado (2026-05-13) — Token IG cifrado (envelope AES-256-GCM por tenant) — memória [[hub-7-1-ig-token-encrypted]].

Próxima mudança planejada: ativação gradual de auto_respond=true por agente após validação humana. Fase 10x (auto-rollback de drift) também pendente de validação real.

2. Cases de uso reais

Case 1: Hari atende lead em DM no WhatsApp

Situação: Lead novo manda mensagem pro número Hari.

Fluxo:

1. Webhook Evolution → record_inbound → whatsapp.message.received event.
2. agents.tasks._dispatch_worker enfileira → abre worker_session(tenant_id) (NullPool isolada — fix loop-mismatch).
3. orchestration.resolve_agent_for_instance(provider_account_id) → consulta agents_instance_mode:
   • Se mode=orchestrator → Manager (Hari neste tenant).
   • Se mode=dedicated → agente fixo.
   • Se mode=team → Manager + pool hint.
4. Cria agents_run(status=queued, channel=whatsapp, intent=dm_respond).
5. brain.respond_dm(channel=whatsapp) monta system prompt (persona + brand_voice + forbidden_topics + business_hours + regras absolutas).
6. Loop tool-use (max 6 iterações): read_products, read_contact_objections, read_brain_config.
7. Texto final → whatsapp.service.send_message → outbound persiste.
8. agents_run.status=completed, output_payload com text + tool_calls + tokens.

Impacto: Resposta em <30s, citando produto correto, no tom da marca.

Case 2: Hub.7 — Agente responde DM no Instagram

Situação: Seguidor manda DM no @maisconsciente.

Fluxo:

1. Webhook IG field=messages → persist em instagram_message.
2. instagram.tasks._dispatch_worker → orchestration.resolve_agent_for_instance(instagram_account.id).
3. brain.respond_dm(channel=instagram) — diferenças vs WhatsApp:
   • Aviso no system: resposta concisa, sem markdown pesado.
   • Max 1500 tokens output.
   • Histórico: últimas 20 msgs do instagram_message (mesmo schema role: inbound→user, outbound→assistant).
4. Token IG decifrado on-demand (instagram_account.access_token_encrypted envelope AES-256-GCM) — memória [[hub-7-1-ig-token-encrypted]].
5. Envia via Graph API /me/messages.

Impacto: Atendimento IG escalado sem usuário ter que sair do app.

Case 3: Hub.8 — Agente responde comentário público no Instagram

Situação: Seguidor comenta "qual o preço?" num post.

Fluxo:

1. Webhook IG field=comments → service.persist_inbound_comment (idempotente via external_id unique).
2. instagram.tasks._dispatch_comment_worker → orchestration.resolve_agent_for_post(media_id).
3. brain.respond_comment — diferente de respond_dm:
   • SEM tools (risco de vazar dado privado em resposta pública).
   • Prompt de segurança extra: "1-2 frases, sem markdown, se sensível → convide pro DM".
   • Histórico: 5 comments anteriores do mesmo post como contexto.
   • Max 400 tokens.
4. Reply via Graph API /{comment_id}/replies.
5. Persiste outbound + status=replied.

Impacto: Comments públicos respondidos sem risco de vazamento; tom sempre conservador.

Case 4: Conselho propõe ação que vai pro Agente Clara

Situação: Conselheiro Commercial detecta lead MQL com score alto sem follow-up em 7d. Propõe mensagem.

Fluxo:

1. council.brain chama tool propose_action → cria council_action(intent=send_message, target_agent_slug=clara, requires_approval=true, status=proposed).
2. Felipe aprova na UI → service.dispatch_approved_action → bridge.dispatch_to_agent.
3. Bridge cria agents_run(input_payload={target_phone, content, crm_contact_id}) com link bridge_run_id (lógico, sem FK).
4. agents.router._execute_dispatch:
   • _decide_order(agent, target_email, target_phone, prefer_channel) → ordem de canais.
   • Tenta whatsapp: whatsapp.service.send_message(to_phone, content, account_id).
   • Se falha → tenta email.
5. agents_run.status=completed + outcome reportado pro council_action.outcome.

Impacto: Conselho "delega" ao agente certo, com audit trail completo (proposed_at → approved_at → dispatched_at → completed_at).

3. Oportunidades de negócio

• Marketplace de templates de agentes: hoje 9 templates hardcoded. Marketplace (community-driven) por vertical (e-commerce, infoprodutor, consultor solo, terapeuta, etc.) com revenue share.
• Tier "Sociedade": despacho automático sem aprovação humana para intents low-risk (templates pré-aprovados com kill switch global). Premium pricing.
• Voz (ElevenLabs): agents_agent.config.voice_enabled previsto mas não implementado. Áudio IA no WhatsApp = diferencial pra comunidades.
• Multi-tenant agency: consultor vende "Hari pré-configurado pra clínicas" como pacote. Whitelabel agentes.
• Agentes verticais como produto SaaS standalone: "Mandir Onboarding" (apenas o template onboarding + canais + analytics) por preço menor que o Suite completo.
• Compliance brasileira: agentes com LGPD-aware (auto opt-out, anonimização). Diferencial em saúde/educação/financeiro.
• Drift detection como serviço: Fase 10x (auto-rollback) é única — vender "garantia de qualidade de IA" pra empresas que treinam agentes.

Riscos comerciais:

• Meta pode mudar política de bots no IG (já aconteceu em 2024 com restrições a auto-replies).
• Anthropic pricing — cada DM custa ~$0.005-0.05 dependendo de tools.
• Risco reputacional: agente respondendo besteira pra cliente é dor pública.

4. Arquitetura interna

Diagrama do fluxo principal — DM WhatsApp

Webhook WhatsApp → record_inbound → whatsapp.message.received event
   ↓
agents.tasks._dispatch_worker [Celery — worker_session NullPool]
   ↓
orchestration.resolve_agent_for_instance(provider_account_id)
   ├─ instance_mode=orchestrator → Manager
   ├─ instance_mode=dedicated → Agent específico
   └─ instance_mode=team → Manager + pool hint
   ↓
INSERT agents_run(status=queued, channel=whatsapp, intent=dm_respond)
   ↓
brain.respond_dm(channel=whatsapp)
   ├─ load brand_voice, forbidden_topics, business_hours
   ├─ load histórico (últimas 20 msgs)
   ├─ build system prompt (persona + brand + regras)
   ├─ tool-use loop (max 6 iter):
   │     read_products, read_contact_objections,
   │     read_brain_config, read_contact_attributes, etc.
   └─ texto final
   ↓
whatsapp.service.send_message → outbound
   ↓
UPDATE agents_run(status=completed, output_payload)

Diagrama do fluxo — Comment Instagram (Hub.8)

Webhook IG field=comments → persist_inbound_comment (idempotente)
   ↓
agents.tasks._dispatch_comment_worker
   ↓
orchestration.resolve_agent_for_post(media_id)
   ↓
brain.respond_comment (SEM tools, prompt seguro, max 400 tokens)
   ↓
service.reply_to_comment → POST /{comment_id}/replies
   ↓
persist outbound + status=replied

Arquivos do módulo

Tasks Celery

Todas usam worker_session (NullPool) — memória [[celery-asyncpg-loop-mismatch]].

Os 9 Templates Pré-Configurados

Importante: slug é nome do agente, não função. Mesmo slug mantém identidade no tempo (memória [[agentes-nomes-nao-funcoes]]).

5. Tabelas + relacionamentos

4 tabelas, prefixo agents_*. Sem FK física cross-módulo.

agents_agent

Definição de persona IA + canais habilitados.

Constraint: UNIQUE(tenant_id, slug).

agents_run

Execução de tarefa (DM, email, comment, etc.).

Índices: (tenant, status).

agents_whatsapp_presence

Presença de agente em grupo WhatsApp (mention-based).

Espelha council_whatsapp_presence mas pra agentes. Mesma estrutura: group_external_id, agent_slug, phone_number_e164, mention_token (@clara, @suporte), proactivity (silent/passive/active), min_caller_role, context_window_days, max_context_tokens.

agents_instance_mode

Roteamento de DM por instância WhatsApp.

Constraint: UNIQUE(tenant_id, provider_account_id).

Relacionamentos cross-módulo

6. API / Endpoints

~15 endpoints sob /api/agents/*.

7. Brain — raciocínio LLM

respond_dm(db, tenant_id, agent, thread_id, contact_phone, channel, pool_hint, target_override)

Modelo: Claude Opus default (configurável via tenant_brain_config.default_council_model).

Tools disponíveis (12 read-only, subset do Conselho):

• read_contact_attributes, read_attribution, read_contact_timeline
• read_patterns, read_knowledge, search_knowledge
• read_products, read_contact_price_inquiries, read_contact_objections
• read_contact_appointments, read_brain_config, read_contact_360

Loop tool-use (MAX_TURNS=6):

• Iter 0: monta system prompt + histórico + user_message → call LLM.
• Stop_reason=tool_use → executa via council_tools.execute_tool em paralelo.
• Adiciona tool_results, próxima iter.
• Stop_reason=end_turn → texto final.

System prompt (_build_system):

1. agent.persona_prompt (base).
2. • ## Voz da marca\n{brand_voice_md} (de tenant_brain_config).
3. • ## NÃO fale sobre\n{forbidden_topics_md}.
4. • ## Horário de atendimento\n{business_hours JSON}.
5. (se pool_hint) + ## Modo time\nVocê é o Gerente, pode mencionar: ....
6. • ## Regras absolutas:
   • Responda em pt-BR.
   • Nunca invente preço, política ou data — consulte ferramentas.
   • Se não sabe → "vou checar e acionar humano".
   • Resposta concisa (1-3 parágrafos WA, 1-2 IG).

Max output: 1500 tokens (DM), 400 tokens (comment).

respond_comment(db, tenant_id, agent, comment_id, pool_hint)

Diferenças vs respond_dm:

• SEM tools — risco de vazamento de dado privado em resposta pública.
• Prompt segurança extra: "Nunca cite dados de outros clientes, preços não publicados, estratégia interna. Se pergunta exige privacidade → convide pro DM."
• 1-2 frases, sem markdown, sem emojis (exceto se brand_voice autorizar).
• Sem iterações — 1 turn só.
• Histórico: 5 comments anteriores do mesmo media_id como contexto.
• Empty string se não puder responder com segurança (não responde).

8. Eventos emitidos / consumidos

Consome

• whatsapp.message.received → _dispatch_worker enfileira run.
• instagram.message.received (Hub.7) → idem.
• instagram.comment.received (Hub.8) → _dispatch_comment_worker.
• council.action.dispatched (via bridge) → _execute_dispatch.

Emite (planejado, ainda log estruturado)

• agents.dispatch.started
• agents.dispatch.completed
• agents.dispatch.failed
• agents.drift.detected
• agents.drift.rolled_back

9. Configuração

Env vars

settings_identity flags

Kill switches em cascata

1. Global: settings_identity.ai_auto_reply_enabled = false.
2. Por agente: agents_agent.is_active = false.
3. Por presença em grupo: agents_whatsapp_presence.is_active = false.
4. Por instância: agents_instance_mode.mode (default orchestrator; sem agente = fallback).
5. Por thread WA: whatsapp_thread.agent_paused_at NOT NULL.
6. Por conta IG: instagram_account.agent_paused_at NOT NULL.

Config por agente (agents_agent.config JSONB — não cravado, planejado)

{
  "tone": "direto" | "reflexivo" | "analítico",
  "auto_respond": True | False,  # quando false, IA gera mas NÃO envia
  "model_tier": "fast" | "default" | "deep",  # Haiku | Sonnet | Opus
  "voice_enabled": True | False,  # ElevenLabs (TBD)
  "max_tokens_per_turn": 1500,
  "schedule": {"weekdays": [1,2,3,4,5], "hours": [8, 22]},
}

10. Operações

Como criar agente novo

Via UI: /admin/agents/new → escolhe template → editar persona → salvar (cria agents_agent). Via API: POST /api/agents/from-template {template_kind, slug, name?, customizations?}.

Como ativar despacho automático

1. Verificar settings_identity.ai_auto_reply_enabled = true (kill switch global).
2. agents_agent.is_active = true.
3. agents_agent.config.auto_respond = true (quando ainda for false, agente gera mas não envia).
4. Para grupo WA: criar agents_whatsapp_presence(is_active=true, mention_token="@<slug>", min_caller_role).
5. Para DM: configurar agents_instance_mode(mode=dedicated, dedicated_agent_id=<id>) ou deixar orchestrator (Manager decide).

Troubleshooting

Sintoma: Agente não responde DM

Diagnóstico em ordem:

1. settings_identity.ai_auto_reply_enabled está true?
2. agents_instance_mode existe pra essa instância? (sem registro = fallback Manager).
3. Manager está ativo (agents_agent.is_active)?
4. Verificar log: docker logs mandir-suite-worker | grep agents.dispatch.
5. Loop-mismatch? (ver memória [[celery-asyncpg-loop-mismatch]] — se sim, conferir worker_session).

Sintoma: Agente envia mensagem mas erro no IG

Causa: token expirado ou decryption falhou. Fix: UI Hub.5 (Instagram) reconectar conta; verificar instagram_account.access_token_encrypted está populado.

Sintoma: respond_comment retorna empty string

Causa: Brain decidiu que pergunta exige privacidade. Comportamento esperado. Verificação: Log agents.dispatch.skipped com reason="privacy_concern".

11. Métricas e observabilidade

Logs estruturados-chave

Dashboards planejados

• /admin/agents/{slug}/avaliacao — outcomes (score_knowledge, score_conversion, etc.) + drift
• /admin/agents/{slug}/custo — tokens × $/token, cost por mês

12. Limitações e débitos técnicos conhecidos

13. Histórico relevante

• 2026-05-13 (commit 8b7107e, mig 0111_council_kill) — Kill switch dos Agentes (ai_auto_reply_enabled) separado do Conselho (council_enabled). Memória [[conselho-e-agentes-kill-switches-separados]].
• 2026-05-13 (commit d6af3dd, mig 0110_ig_comments) — Hub.8 deployado: comments IG → agente.
• 2026-05-13 (commit 7e5a9c, mig 0109_ig_token_envelope) — Hub.7.1: token IG cifrado em envelope AES-256-GCM. 3 contas backfilladas.
• 2026-05-13 (commit 4db4beb, mig 0108) — Hub.7 deployado: DM IG → agente.
• 2026-05-13 — 6 agentes seeded em prod no Mais Consciente (modo rascunho).
• 2026-05-13 (commit b536768) — _dispatch_worker migrado pra worker_session (NullPool ad-hoc) — fix loop-mismatch.

Apêndices

A. Diferenças respond_dm vs respond_comment

B. Glossário

• Manager: o Gerente. Único por tenant (is_orchestrator=true). Orquestra DMs em modo orchestrator ou team.
• Pool hint: quando mode=team, lista de slugs no system prompt do Manager pra ele "delegar mentalmente".
• Drift: score de outcomes caindo após mudança de prompt.
• Auto-rollback: Fase 10x — se drift detectado dentro de janela, persona_prompt volta ao valor anterior.
• Meta-judge: Haiku que rotula outcomes (buying_signal, score_conversion). Calibração semanal compara com Sonnet.
• Bridge: interface contratual Conselho ↔ Agentes (ADR 0015). council_action.bridge_run_id = agents_run.id (lógico, sem FK).
• Instance mode: orchestrator (Manager decide) / dedicated (1 agente fixo) / team (Manager + pool).