name: cidadao-ai-agents
description: Use ao trabalhar com qualquer agente do Cidadão.AI (arquivos em src/agents/*.py como zumbi.py, anita.py, abaporu.py, etc.). Carrega catálogo dos 20 agentes operacionais + 2 frameworks base, suas responsabilidades, categoria e padrão de invocação. Ative quando o usuário mencionar nomes de agentes, criar/modificar agentes, ou orquestrar fluxos multi-agente.
Cidadão.AI Agents
O Cidadão.AI tem 20 agentes operacionais + 2 frameworks base, todos batizados com figuras históricas brasileiras. Cada agente é um único arquivo em src/agents/. Não inventar agentes — use a tabela abaixo e o nome em src/agents/<nome>.py.
Frameworks base (não são agentes)
| Arquivo |
Função |
deodoro.py |
Base framework — todo agente herda dele |
base_kids_agent.py |
Base para agentes do programa Educação (Monteiro Lobato, Tarsila) |
Agentes — Categoria, arquivo e responsabilidade
Core Transparency (4)
| Agente |
Arquivo |
Responsabilidade |
| Zumbi dos Palmares |
zumbi.py (+ zumbi_wrapper.py) |
Investigador — detecção de anomalias |
| Anita Garibaldi |
anita.py |
Analista — análise de dados |
| Tiradentes |
tiradentes.py |
Repórter — geração de relatórios |
| Obaluaiê |
obaluaie.py |
Detector de corrupção |
Orchestration (3)
| Agente |
Arquivo |
Responsabilidade |
| Abaporu |
abaporu.py |
Master orchestrator — coordena workflows multi-agente |
| Ayrton Senna |
ayrton_senna.py |
Semantic router — encaminha queries do usuário para o especialista certo |
| Nanã |
nana.py |
Memória de contexto — mantém estado entre interações |
Specialized (9)
| Agente |
Arquivo |
Responsabilidade |
| José Bonifácio |
bonifacio.py |
Análise legal |
| Maria Quitéria |
maria_quiteria.py |
Segurança / compliance |
| Machado de Assis |
machado.py |
Análise textual |
| Oxóssi |
oxossi.py |
Caçador de dados (data hunting) |
| Lampião |
lampiao.py |
Foco regional / dados estaduais |
| Oscar Niemeyer |
oscar_niemeyer.py |
Agregação de dados |
| Drummond |
drummond.py (+ drummond_simple.py) |
Comunicação / interface conversacional |
| Ceuci |
ceuci.py (+ ceuci_ml_models.py) |
ETL + predição (ML) |
| Dandara |
dandara.py |
Equidade social / análise interseccional |
Education & Design (4)
| Agente |
Arquivo |
Responsabilidade |
| Santos Dumont |
santos_dumont.py |
Educação adulta |
| Lina Bo Bardi |
bo_bardi.py |
Frontend design / UX |
| Monteiro Lobato |
monteiro_lobato.py |
Programação para crianças |
| Tarsila do Amaral |
tarsila.py |
Design para crianças |
Padrão de invocação
Quando uma query chega:
User → API route (chat.py) → ayrton_senna (semantic router)
↓
decide qual agente especialista
↓
abaporu.py se workflow complex
↓
agente especialista executa
↓
nana.py salva contexto
↓
resposta volta
Convenções ao adicionar/editar agentes
- Lazy loading: agentes são carregados sob demanda via
services/agent_lazy_loader.py. Não importar agentes diretamente em routes — usar o loader.
- Pool: agentes ativos vão para
infrastructure/agent_pool.py. Seguir o agent_pool_interface.py.
- Wrappers: alguns agentes têm wrapper (
zumbi_wrapper.py, metrics_wrapper.py) para metrics/cache. Manter wrapper separado do core.
- Naming: arquivo em
snake_case (sobrenome simples ou primeiro nome). Classe interna em PascalCase.
- Testes:
tests/unit/test_agents/test_<nome>.py. Sempre setar JWT_SECRET_KEY=test SECRET_KEY=test antes de rodar.
- Identidade brasileira: cada agente tem voz/personalidade alinhada à figura histórica. Ver
services/agent_voice_profiles.py.
Anti-patterns
- ❌ Importar
from src.agents.zumbi import Zumbi em route — usa o lazy loader
- ❌ Criar um agente "novo" com nome estrangeiro (ex.: "JohnSmithAgent") — quebra identidade do projeto
- ❌ Modificar
deodoro.py (base framework) sem revisar todos os 20 agentes que herdam dele
- ❌ Adicionar lógica de roteamento em outro lugar que não
ayrton_senna.py
- ❌ Persistir estado de contexto fora de
nana.py
Referências
- Catálogo completo + métricas:
cidadao.ai-backend/CLAUDE.md
- Profiles de voz:
src/services/agent_voice_profiles.py
- Histórico no
cidadao.ai-docs repo
By