Plataforma SAFEHARN

HARN — Catálogo de Automações Inteligentes

Plataforma de agentes composáveis para mercado financeiro, RH e outros setores. Cada automação é uma receita reutilizável de Prompt + SKILLs + RULEs + Tools + LLM.

Oportunidades mapeadas

Verticais de mercado

Capacidades da plataforma

Entregas recentes

Últimas implementações de segurança, deploy, qualidade e documentação de arquitetura — base para as capacidades da plataforma abaixo.

Qualidade

Evaluation Framework v1

Datasets/Test Cases/Suites/Runs com evaluators determinísticos sobre AgentExecution (tools, retrieval, tokens, latência, custo); fila RabbitMQ e UI Evaluation; regression a partir de execuções.

Plataforma

Versionamento completo de agentes

Agent Version com pins (prompt/skills/rules/tools/LLM); ambientes DEV→TEST→STAGING→PRODUCTION; clone, promote, rollback e execução por versão do ambiente.

Governança

Gerenciamento de API-KEY

Organization como tenant, departamentos e usuários; configs LLM com bindings e permissões por agente/HarnFlow; resolução em cascata USER → DEPARTMENT → ORGANIZATION no execute; sidebar Governança.

FinOps

Governança de custos

Usage ledger (tokens + custo USD), pricing por modelo, quotas/budget por escopo, rate limits Redis, fallback de modelo governado e telas Consumo/Quotas.

Segurança

Fail-fast de secrets e gates de deploy

JWT/AMQP/PYTHON_RUNNER_API_KEY obrigatórios no boot; seed admin bloqueado em production; Telegram exige credenciais no startup.

Deploy

Contrato Dev/Docker alinhado à produção

DNS interno harn-api / harn-python-runner; portas 3210/3211/3212/3280 preservadas; .env.example só para pnpm local.

Qualidade

Testes de alto valor + CI

ACL (resource-access), BFF (backend-proxy), messaging (processResponse), sql-params; pnpm test na raiz e GitHub Actions (Node + unittest do runner).

Arquitetura

Docs de sistema e ADRs

C4 containers, auth E2E, mapa de filas, rede Docker e contratos Telegram em docs/architecture; ADRs de BFF cookie→Bearer e dual auth.

Código

Field-encryption unificado

AES-256-GCM centralizado em @harn/shared; API e worker consomem a mesma implementação.

Produto

Telegram + MagicWork em produção

Canal operacional completo e geração de agentes a partir de linguagem natural (já documentados nas seções abaixo).

Indicadores e Oportunidades

Distribuição por vertical, maturidade das integrações e impacto estimado.

Oportunidades por vertical

8 financeiro · 5 RH · 7 outros setores

Maturidade das integrações

Status real da plataforma HARN

Impacto estimado (%)

Valores ilustrativos para apresentação executiva

Capacidades da Plataforma

Tools, canais e capabilities — incluindo Versioning, Evaluation e FinOps — com status de implementação. HarnFlow tem showcase visual abaixo.

PROVIDERPronto

SERPRO, Serasa, bureaus com bloqueio inteligente

APIPronto

Integrações REST configuráveis

PYTHONPronto

Regras de negócio no sidecar FastAPI autenticado

WEBPronto

Busca pública via SearXNG/Tavily

TELEGRAMPronto

Vínculo, dual auth, execução e push de resultado no chat

DBPronto

Query Builders + db-runtime (SQL parametrizado)

EMAILPronto

Envio via ApiConfig (ex.: gateway SMTP/HTTP) com schema e domínio email no worker

VECTOR_SEARCHPlanejado

Stub hoje; Qdrant já usado para tools — RAG de docs é o próximo passo

WhatsAppPlanejado

Atendimento e coleta de documentos

RAGPlanejado

Base de conhecimento / RAG de verdade — Qdrant já existe; docs por agente, citações

CRON_HOOKSPronto

Agendamento e gatilhos — cron, webhook de entrada e eventos internos

HITLPlanejado

Human-in-the-loop — pausar tools críticas; aprovar no Web + Telegram

OBSERVABILITYPronto

Tracing de execução — logs por step, métricas (tokens, loops, tools), auditoria em PostgreSQL e replay na UI de Agent Runs

FINOPSPronto

Governança de custos LLM — usage ledger (tokens + USD), pricing por modelo, quotas/budget por escopo, rate limits, fallback de modelo e telas Consumo/Quotas

MEMORYPronto

Memória / conversa contínua — thread por chave composta de inputs

TOOLS_CATALOGParcial

Completar catálogo de tools — RAG, webhooks Slack/Teams

VERSIONINGPronto

Versionamento completo — Prompt/Skill/Rule/Tool/HarnFlow/RAG + Agent Version com pins; ambientes DEV→TEST→STAGING→PRODUCTION, clone, promote e rollback

EVALUATIONParcial

Evaluation Framework v1 — Datasets, Test Cases, Suites, Runs assíncronos e evaluators determinísticos (tools/retrieval/performance/custo); Compare e Quality Gates na sequência

MULTI_TENANTPronto

Tenant Organization com departamentos/usuários, API-KEY LLM por org (bindings + permissões) e resolução em cascata USER → DEPARTMENT → ORGANIZATION no execute

HarnFlowPronto

Designer visual de orquestração multi-agente. Monta fluxos (DAG) conectando agentes do catálogo a LLM, prompts, skills e rules; valida o grafo, persiste e executa no worker (FlowRunner) com paralelismo por waves — útil para automações compostas sem depender só do orquestrador LLM.

Versioning

Pronto

Publique agentes com pins imutáveis (prompt, skills, rules, tools, LLM) e promova entre ambientes com rastreio — sem editar “ao vivo” o que está em produção.

Ambientes DEV → TEST → STAGING → PRODUCTION
Clone de versão, promote e rollback (produção)
Execução resolve a versão do ambiente (não o head solto)

Evaluation

Parcial

Transforme execuções instrumentadas em suites repetíveis: datasets, test cases, evaluators determinísticos e runs assíncronos contra uma versão do agente.

Datasets / Suites / Runs com breakdown por evaluator
Tools, retrieval, tokens, latência e custo (FinOps)
Regression a partir de uma execução (Agent Runs) — Compare e Quality Gates na sequência

HarnFlow

Pronto

Para que serve: orquestrar vários agentes em um fluxo visual (DAG), compondo LLM, prompts, skills e rules no canvas; validar, salvar e executar a automação composta no worker — sem depender apenas do plano gerado pelo orquestrador LLM.

Designer HarnFlow com canvas de agentes, skills e painel de propriedades — Designer visual HarnFlow — canvas de orquestração multi-agente

HARN — Motor de Automação

Orquestração de Agentes HARN

Arquitetura e Diferenciais

Visão executiva do fluxo da plataforma. Para diagramas técnicos detalhados do worker (bootstrap, agent loop, orquestrador), veja a seção Execução do Worker.

API / UI / Telegram

Entrada da solicitação

RabbitMQ

Fila de tarefas

Worker

Motor de execução

LLM + Tools

Planejamento e integração

Resultado auditável

JSON validado + logs

Orquestrador multi-domínio

Bloqueio cruzado valido=false

Validação JSON Schema com retry

Cache de sessão para provedores

Auditoria completa em PostgreSQL

Versionamento por ambiente (DEV→PROD)

Evaluation suites com evaluators determinísticos

Governança de custo LLM (FinOps)

Fail-fast de secrets (JWT, AMQP, runner)

Docs de arquitetura + ADRs

CI com testes Node + Python Runner

Integração Telegram

Canal operacional pronto: vincule sua conta, liste e execute agentes pelo bot e receba o resultado no chat.

Carregando status…

A vinculação e o desvínculo ficam em Conta → Telegram.

Como vincular

1Abra Conta → Telegram na plataforma web
2Gere o link de vinculação
3Abra o deep link no Telegram e inicie a conversa com o bot
4Confirme o vínculo — a web detecta automaticamente

Comandos do bot

/agentesListar agentes e executar
/funcoesListar funções disponíveis
/status <ticket>Status da execução
/resultado <ticket>Resultado final
/cancelarCancelar coleta de parâmetros
/helpAjuda e status do vínculo

Fluxo de execução

Vínculo

Conta web ↔ chat Telegram

/agentes

Lista paginada com ACL do usuário

Inputs

Coleta dos parâmetros do agente

Ticket

Execução assíncrona no worker

Resultado

Push automático no chat

MagicWork

Gere um agente completo a partir de uma tarefa em linguagem natural: Prompt + SKILL + RULE + Agente (e Python/tool se o plano pedir).

Da descrição da automação ao agente executável

A geração acontece na página MagicWork — aqui só explicamos o fluxo.

Como usar a página

1Descreva a tarefa (obrigatório); nome e grupo do agente são opcionais
2Opcional: dite a tarefa por voz com a assistente Luna
3Clique em “Gerar agente automaticamente”
4Acompanhe o progresso: análise → Python → SKILL → RULE → Prompt → Agente
5Abra os recursos criados ou execute o agente

O que é gerado

AgentOrquestrador com inputs, template e playbooks
SkillPlaybook procedural (SKILL)
RulePlaybook de regras e formato de saída
PromptInstruções e schema do agente
Python + ToolOpcional — função e tool PYTHON quando o plano exigir
Tools do catálogoSugestões; aviso se ainda não existirem na plataforma

Fluxo resumido

Tarefa

Descrição em linguagem natural

Plano LLM

Monta a receita dos artefatos

Criação

Recursos em sequência

Resultado

Links e execução; rollback se falhar

Execução do Worker — Arquitetura Técnica

Diagramas oficiais do motor de execução em apps/worker: inicialização, fluxo de tarefas, orquestrador, agent loop e visão consolidada do carregamento e execução de tools.

Bootstrap do Worker

Sequência de inicialização ao subir o processo worker.

Renderizando diagrama…

Health HTTP na porta 3202
Carrega tools do PostgreSQL e indexa no Qdrant
Registra playbooks e inicia consumers RabbitMQ

Fonte: apps/worker/docs/diagramas/01-bootstrap.mmd

Como Empacotar para Venda

Cada produto é um agente configurado — mesma plataforma, composição diferente.

Agente = Prompt + SKILLs + RULEs + Tools + Inputs + Canal

Prompt

Instruções + task + outputSchema

SKILLs

Procedimentos por domínio

RULEs

Restrições e formato de saída

Tools

PROVIDER, API, PYTHON, canais

Inputs

CPF, telefone, valores...

Canal

UI, API, Telegram, WhatsApp

Catálogo de Oportunidades

20 automações mapeadas organizadas por vertical de mercado.

KYC / Onboarding completo

Valida identidade, documento, telefone, PEP e listas restritivas — com versão controlada do agente e trilha auditável.

PROVIDERWEBPYTHONVERSIONING

Abertura de conta em minutos com rastreio auditável

Análise de crédito pré-aprovada

Cruza bureau, renda, histórico interno e política de crédito.

PROVIDERDBPYTHON

Pré-análise antes do analista humano

Antifraude PIX/TED

Analisa titularidade, padrão de comportamento e listas negras.

APIPROVIDERTELEGRAM

Bloqueio preventivo com explicação estruturada

Conciliação bancária

Compara extratos, boletos e lançamentos internos.

DBPYTHONAPI

Menos trabalho manual no back-office

Validação de NF-e

Valida chave, CNPJ emitente, duplicidade e inconsistências.

APIWEBPYTHON

Contas a pagar com menos fraude

Compliance PLD-FT

Monitora PEP, OFAC, operações atípicas e mídia adversa.

WEBPROVIDERDB

Relatórios de compliance com evidências

Cobrança inteligente

Prioriza devedores e valida contato antes de acionar.

PROVIDERDBTELEGRAM

Recuperação mais eficiente

Análise de contratos

Extrai cláusulas e compara com política interna.

PYTHONVECTOR_SEARCH

Revisão jurídica em minutos

Blueprint — Análise de Crédito Pré-Aprovada

Configuração completa para criar na UI: agente, tools, SKILLs, RULEs e prompt.

Agente

Campo	Valor
Nome	Análise de Crédito Pré-Aprovada
Grupo	credito
Orchestrator	true
maxLoops	8
playbookSlugs	consulta-cpf, consulta-serasa, calculo-score-credito, saida-credito-json

Inputs do Agente

key	name	type	required	descrição
cpf	CPF do solicitante	cpf	sim	Documento principal
renda_declarada	Renda declarada	number	sim	Renda mensal em R$
valor_solicitado	Valor solicitado	number	sim	Montante do crédito
produto	Produto	text	sim	Ex: pessoal, consignado, veículo
prazo_meses	Prazo (meses)	number	não	Prazo desejado

executionPromptTemplate

Analise o crédito para CPF {{cpf}}, renda R$ {{renda_declarada}},
valor solicitado R$ {{valor_solicitado}}, produto {{produto}}.
@skill:consulta-cpf @skill:consulta-serasa @skill:calculo-score-credito
@rule:saida-credito-json

Tools a criar na UI

Nome	Tipo	Grupo	keyReference / detalhe
validar_cpf	PROVIDER	receita	nome_chave do site_provedor CPF
consulta_serasa_score	PROVIDER	serasa	nome_chave bureau Serasa
calcular_comprometimento_renda	PYTHON	database	função Python no sidecar
consultar_historico_cliente	DB	database	query histórico inadimplência
notificar_analista_credito	TELEGRAM	—	notificação opcional

Função Python — calcular_comprometimento_renda

Entrada: renda_declarada, valor_solicitado, prazo_meses, score_externo

Saída: { comprometimento_pct, score_interno, faixa_risco }

Regra: comprometimento > 30% → risco elevado

SKILLs

consulta-cpf

---
name: consulta-cpf
requiredTools: [validar_cpf]
toolOrder: [validar_cpf]
---
Validar CPF na Receita antes de qualquer consulta paga.
Se valido=false, interromper fluxo de bureau.

consulta-serasa

---
name: consulta-serasa
requiredTools: [consulta_serasa_score]
optionalTools: [consultar_historico_cliente]
toolOrder: [consultar_historico_cliente, consulta_serasa_score]
---
Consultar histórico interno (barato) antes do Serasa (pago).

calculo-score-credito

---
name: calculo-score-credito
requiredTools: [calcular_comprometimento_renda]
---
Consolidar dados e calcular score interno + limite sugerido.

RULE — saida-credito-json

---
name: saida-credito-json
alwaysApply: true
outputValidation:
  mode: json_schema
  schema:
    type: object
    required: [aprovado, limite_sugerido, taxa_sugerida, score_risco, motivos]
    properties:
      aprovado: { type: boolean }
      limite_sugerido: { type: number }
      taxa_sugerida: { type: number }
      score_risco: { type: string, enum: [baixo, medio, alto] }
      motivos: { type: array, items: { type: string } }
      documentos_pendentes: { type: array, items: { type: string } }
  onFailure: retry_llm
maxOutputRetries: 3
---
Resposta sempre em JSON estruturado para integração com core bancário.

Prompt

systemInstructions: Você é analista de crédito automatizado. Priorize consultas baratas. Não aprove se CPF inválido ou score_risco=alto.

task: Realizar pré-análise de crédito com limite e taxa sugeridos.

outputSchema: Espelha a RULE saida-credito-json

Fluxo de Execução

UI/Telegram

Envia cpf, renda, valor

Worker

Stage 1: validar_cpf (barato)

Receita

Se valido=false → reprova sem bureau

Consulta histórico interno

Serasa

Consulta bureau (pago)

Python

Calcula score e limite

Worker

Retorna JSON aprovado/limite/taxa

Blueprint — Admissão Digital RH

Resumo compacto com opção de expandir detalhes completos.

Campo	Valor
Nome	Admissão Digital de Colaborador
Grupo	rh
playbookSlugs	validar-docs-admissao, consulta-antecedentes, saida-rh-json

Inputs

cpf (cpf) — CPF do candidato
telefone (text) — Celular com DDD
email (email) — E-mail pessoal
cargo (text) — Cargo pretendido
data_admissao (date) — Data prevista

Tools

validar_cpf — PROVIDER (receita)
validar_telefone — PROVIDER (telefone)
consulta_antecedentes — PROVIDER (serasa)
enviar_boas_vindas — EMAIL (email)
notificar_rh — TELEGRAM (—)

SKILLs

validar-docs-admissao — Ordem: CPF → telefone → e-mail
consulta-antecedentes — Só após documentos válidos

RULE saida-rh-json: { aprovado, pendencias[], checklist_onboarding[], nivel_risco }