Framework · Python sem dependências
O agente é ferramenta. O centro é o resultado.
Monte apps de IA em que o LLM roda dentro de um workflow fixo, a pessoa aprova toda ação e a política da empresa vira código testado.
Monte apps de IA em que o LLM roda dentro de um workflow fixo, a pessoa aprova toda ação e a política da empresa vira código testado.
O agentic-app é um framework em Python para empresas construírem apps de IA a partir de um resultado de negócio, e não a partir do agente. Ele serve para quem precisa colocar IA dentro de um processo real (RH, gestão de pessoas, atendimento) com controle: o LLM roda dentro de um workflow fixo, toda ação externa espera aprovação humana, regras com número viram código testado e cada execução fica registrada. Vem com um app completo de exemplo (coaching de gestor) e roda só com o Python 3 instalado, sem chave e sem internet.
A pergunta de partida não é "que agente vamos criar?". É "quem decide o quê, e como medimos se ficou melhor?". O agente entra depois, como uma peça do processo.
Cada uso de LLM é um nó entre outros quatro: contexto, código, condição e formatação. Mesma entrada, mesma saída.
O workflow só propõe. O e-mail fica na fila até a pessoa ler, editar e aprovar. Tudo vai para o audit log.
O manual de férias vira funções com entrada estrita e 13 testes de política. Mudou um número, um teste quebra.
Cada pilar tem um arquivo e pelo menos um teste. Use a lista para revisar qualquer app de IA da sua empresa, mesmo que não use este código.
Canvas com pessoa usuária, decisão e métrica de sucesso antes de pensar em agente.
templates/canvas-resultado.md
Nós contexto → código → condição → LLM → formatação. O modelo é escolhido pela tarefa, não por gosto.
workflow.py · config.py
O botão do painel envia o input para o workflow e o resultado volta na própria tela, como rascunho editável.
painel.html · serve.py
Toda ação externa passa por revisão, edição e aprovação. Campos sensíveis, como o destinatário, ficam travados.
acoes.py
Observam os dados (meta vencida, 1:1 atrasado, engajamento caindo) e sugerem próximos passos com botão de executar.
workflow proximos_passos
Classifica a pergunta, carrega só a política certa e dá ao agente só as ferramentas dela. Busca fica para pergunta aberta.
policies/ferias.py
Papéis que podem executar, identidade de serviço com escopo mínimo e audit log com hash encadeado.
seguranca.py
Manual, agendado (segunda 08:00) e por evento (e-mail recebido), declarados no próprio JSON do workflow.
gatilhos.py
Relatório em HTML e PDF, gerado por workflow, no lugar de uma parede de texto.
relatorio.py
O motor confere quem pediu, assume a identidade do workflow, valida a entrada e roda os nós em ordem. A saída é JSON validado. Ações viram propostas. Uma linha de auditoria por execução.
perfil (contexto, identidade svc-rh) → categoria (LLM classifica: férias, licença parental ou outro) → condição → dados (código tira da pergunta os números) → agente (LLM escolhe entre as ferramentas SÓ daquela política) → explicação (código) → formatação.
equipe (contexto) → metas vencidas (código) → tem pendência? (condição) → rascunhos (LLM redige um por pessoa) → formatação valida e propõe 6 e-mails. Nenhum sai antes da aprovação.
Nada para instalar com pip. Nenhuma chave de API. Os testes bloqueiam a rede de propósito.
Linux, Mac ou Windows.
# conferir python3 --version
Para baixar o repositório.
git --versionSó se quiser trocar o LLM fake por um modelo local.
# opcional ollama list
Os quatro primeiros passos rodam o exemplo. Os outros mostram o que você troca para a sua empresa. O roteiro completo, com checklist de implantação, está em docs/PASSO-A-PASSO.md.
104 checks, sem rede. A última linha tem que ser OK.
git clone https://github.com/inematds/agentic-app cd agentic-app bash tests/run.sh # 104 checks, 0 falhas → OK
Executa os 5 workflows: RBAC negando, rascunhos, aprovação com edição, assistente de RH, agendado de segunda 08:00, evento de e-mail recebido e relatório.
python3 -m agentic_app.demo # gera saida/relatorio.html, saida/relatorio.pdf, saida/audit.jsonl
Troque de pessoa no topo (gestora, RH, colaborador) e veja o que cada papel pode fazer.
python3 -m agentic_app.serve --porta 8765 # http://127.0.0.1:8765 (só na sua máquina)
O script muda nove números do manual, um de cada vez, e confere que algum teste quebra.
bash tests/prova_mutacao.sh # 9× "quebrou (bom)" → OK
Pessoa usuária, decisão, custo de hoje e um número de sucesso com prazo. Sem métrica, não comece.
cp templates/canvas-resultado.md docs/meu-canvas.md
Uma constante por número do documento, um teste por limite (o valor exato e o vizinho).
cp templates/politica_modelo.py agentic_app/policies/reembolso.py cp templates/test_politica_modelo.py tests/test_reembolso.py
Contexto → código → condição → LLM → formatação. A ação externa vai em propor_acao, com os campos editáveis. Mova para a pasta workflows/ do seu app só depois de registrar o contexto e a função que ele usa.
cp templates/workflow-modelo.json meu_workflow.json python3 -c "from agentic_app.workflow import carregar_spec as c; c('meu_workflow.json')"
Quem executa cada workflow, com qual conta de serviço ele age e quem aprova o que ele propõe.
cat templates/permissoes.json
O fake fica nos testes. Para um modelo local, uma variável. Para outro provedor, uma subclasse de LLM.
AGENTIC_LLM=ollama python3 -m agentic_app.demo
Dados fictícios. A gestora vê a equipe, gera follow-ups para quem não bateu a meta, recebe sugestões do agente de fundo e responde dúvidas de férias com a política codificada.
relatorio_equipe: 12 pessoas, 16 metas, 7 vencidas. Também sai em PDF.| Componente | Workflow | Nós | Quem executa | Age como |
|---|---|---|---|---|
| Follow-up de metas | followup_metas | 6 | gestor, sistema | svc-coaching |
| Próximos passos | proximos_passos | 6 | sistema, gestor | svc-coaching |
| Convite para 1:1 | convite_1a1 | 4 | gestor | svc-coaching |
| Assistente de RH | assistente_rh | 10 | colaborador, gestor, rh, sistema | svc-rh |
| Relatório | relatorio_equipe | 4 | gestor, rh, sistema | svc-coaching |
O painel do gestor é a tela de trabalho. O painel executivo responde a quem patrocina o app, com números calculados do audit log, da fila de aprovações, da caixa de saída e dos dados do app. Nenhum número vem de LLM.
A métrica do canvas contra a meta e a linha de base, com status "atingiu" ou "não atingiu". Na demo: metas concluídas 31,2%, engajamento médio 76,7 e 6 pessoas em risco.
Execuções por workflow e por gatilho (clique 7, horário 1, evento 1), rascunhos aprovados, editados e rejeitados, tempo até aprovar e sugestões do agente de fundo aceitas (1 de 10).
Acessos negados por papel, ferramentas barradas pelo escopo mínimo, corrente de hash íntegra ou quebrada (com a linha) e a % de ações externas com aprovação, que tem que ser 100%.
Chamadas por workflow e por modelo (o FakeLLM conta igual), tokens estimados e custo pela tabela de templates/indicadores.json, que vem zerada.
De 3 a 5 frases curtas montadas por código, na ordem crítico → atenção → ok. Corrente quebrada ou e-mail sem aprovação sobem para o topo.
O painel é o workflow painel_executivo, com identidade só de leitura. Colaborador e gestor recebem 403, e a tentativa vira uma linha workflow.negado no audit.
python3 -m agentic_app.demo # seção 10: resumo executivo python3 -m agentic_app.serve # http://127.0.0.1:8765/executivo?usuario=dora
O executivo mostra se o app entrega agora. O painel de tendências usa o histórico semanal para dizer o ritmo de cada número, quando a meta chega (ou que não chega no trimestre) e o que está piorando antes de virar problema.
Regressão linear simples sobre as semanas: "no ritmo atual, a meta é atingida em DD/MM" ou "não é atingida até o fim do trimestre". Meta já batida mas piorando mostra a data em que sai.
Três semanas seguidas no sentido ruim viram alerta. Na demo: engajamento médio caindo há 8 semanas e 4 pessoas com 3 quedas seguidas (Carla, Henrique, Elisa, Lucas).
Regra explícita no código: cada 1:1 a mais por semana cobre uma pessoa com meta vencida. Com 5 por semana, 42,9% vira 76,2% e a meta de 90% chega em 28/12/2026.
O workflow snapshot_indicadores grava a foto da semana toda segunda 07:00 em saida/historico.jsonl. Com menos de 4 semanas, o painel diz "histórico insuficiente".
Workflow painel_tendencias com identidade só de leitura. O LLM só costura a narrativa com frases já calculadas; trocar o LLM não muda nenhum número.
python3 -m agentic_app.demo # seção 11: snapshot + tendências # http://127.0.0.1:8765/tendencias?usuario=estela
Executivo e tendências são para quem decide. O Centro de Comando é para quem acompanha ao vivo e age na hora. Duas abas: Agentes (Agent Control Tower) e Negócio (Mission Control).
Semáforo por workflow (ok, atenção, falha, pausado), última execução, próximo disparo agendado, fila de aprovação por idade com SLA de 24 h, falhas e acessos negados, corrente do audit e os últimos eventos.
Pausar (o disparo fica no audit e não roda; os outros agendados seguem), retomar, rodar agora, reexecutar e escalar uma aprovação parada. Só o papel operacao e o admin. Operação nunca aprova nem envia.
A métrica do canvas contra a meta e quantas conversas faltam (na demo: 42,9%, faltam 4). Fila de decisão: quem está em risco, em que pé está e a próxima ação, com botão para acionar o agente, aprovar ou rejeitar.
Botão sem permissão aparece desabilitado com o motivo, e o servidor confere de novo. Toda ação e toda negativa vão para o audit. Reexecutar só refaz o que não exige guardar a entrada da pessoa.
python3 -m agentic_app.demo # seção 12: pausar, escalar, painel # http://127.0.0.1:8765/comando?usuario=otavio
Agentes, Negócio, Executivo e Tendências ganharam o layout dos painéis de BI: números grandes no topo, filtros na lateral, gráficos no meio e, embaixo, o detalhe com as ações. Clicar num gráfico filtra o resto da página.
Uma barra no topo leva aos quatro painéis. Cada um continua com o seu papel: quem não pode ver recebe 403 e a tentativa fica no audit.
Barra, dia, fatia ou cartão viram filtro (?workflow=…&situacao=falha). Os filtros ativos aparecem como etiquetas; clicar de novo tira. O link pode ser guardado e compartilhado.
Colunas, barras, roscas e linhas desenhadas em Python, sem biblioteca nem CDN. Tooltip ao passar o mouse, legenda sempre que há duas ou mais séries, cor de status sempre com rótulo.
python3 -m agentic_app.simular roda o motor de verdade com relógio simulado (fictício, sempre igual) para os gráficos terem o que mostrar.
python3 -m agentic_app.simular python3 -m agentic_app.serve
Os vídeos de explicação vão aparecer aqui.
O agentic-app não substitui os outros kits INEMA. Ele fica em cima deles.
O agente da empresa em arquivos: identidade, skills, regras e medição. Responde quem é o agente e como ele trabalha aqui.
Como os agentes descobrem, conectam e usam as ferramentas que você já tem. Responde por onde o agente chega nas ferramentas.
A aplicação que a pessoa de negócio usa: tela, workflow fixo, política em código, aprovação e auditoria. Responde que resultado a empresa ganha.
A versão 1.0.0 é o núcleo completo com um app de referência. Depois vieram o painel executivo (1.1.0), o de tendências (1.2.0), o Centro de Comando (1.3.0) e o layout comum de BI nos quatro painéis (1.4.0).