Athena -- AI Agent para TOTVS Protheus

Athena é um agente de IA em produção que responde perguntas de negócio consultando o ERP TOTVS Protheus. Atende centenas de usuários de múltiplas empresas, times de RH, logística, financeiro e operações, cada uma com sua própria instância de banco de dados, dialeto SQL e regras de negócio.

A escala do problema

TOTVS Protheus é um dos ERPs mais complexos do mercado brasileiro. Cada cliente tem centenas de tabelas, joins não-óbvios, campos com nomes codificados e regras de negócio que variam por módulo, por empresa e por configuração de implantação.

O desafio adicional: as empresas atendidas rodam bancos diferentes. Algumas usam Oracle, outras SQL Server, outras PostgreSQL. A mesma pergunta de negócio exige queries sintaticamente diferentes dependendo do cliente.

Fazer um usuário de RH conseguir perguntar "qual a taxa de absenteísmo do mês passado por setor?" e receber uma resposta correta, sem saber nada de SQL, sem saber qual tabela usar, sem conhecer as regras de cálculo do módulo, era o objetivo.

O que não funcionou primeiro

A abordagem inicial foi colocar toda a base de conhecimento no system prompt: queries de referência, regras de negócio, mapeamento de tabelas, diferenças de sintaxe por banco.

Funcionava para perguntas simples. Quebrava para perguntas complexas.

O modelo passava a alucinar de formas sutis, as piores do ponto de vista de produção: não erros óbvios, mas filtros incorretos ou incompletos. Uma query que rodava, retornava resultado, mas trazia dado errado porque faltava um filtro de competência, ou porque usou a tabela de movimentação no lugar da tabela de saldo.

O problema não era só qualidade. Era viabilidade econômica.

Prompt gigante significa latência alta e custo alto por query. Com centenas de usuários simultâneos, cada request chegava com um contexto enorme que o modelo precisava processar, mesmo quando a pergunta era simples e usaria apenas 2% daquele conhecimento. Inviável em produção.

A conclusão foi direta: o sistema precisava de recuperação seletiva de contexto, não contexto total sempre.

A arquitetura

A solução adotada usou LangGraph para orquestrar o fluxo e um nó de RAG customizado antes do agente principal de geração de SQL.

O fluxo funciona assim:

A pergunta do usuário entra no grafo LangGraph
Um nó de recuperação semântica busca no PGVector o bloco de conhecimento relevante para aquela pergunta específica
O bloco recuperado, e apenas ele, é injetado no contexto do agente
O agente gera a query SQL com contexto cirúrgico e sem ruído de outros módulos
A query é executada no banco do cliente (Oracle, SQL Server ou PostgreSQL)
O resultado é formatado e devolvido ao usuário em linguagem natural

A separação entre nó de recuperação e nó de geração foi uma decisão arquitetural deliberada. Com LangGraph, cada etapa do fluxo é um nó explícito no grafo, com estado próprio e rastreável. Isso tornou o sistema auditável: é possível inspecionar o que foi recuperado, o que foi gerado e onde o erro aconteceu quando algo falha.

A decisão técnica central: chunking por delimitador semântico

A base de conhecimento foi estruturada num documento Markdown com mais de 100 blocos por módulo. Cada bloco contém:

A query de referência para aquele tipo de consulta
As tabelas envolvidas e seus relacionamentos no Protheus
Os filtros obrigatórios e as regras de negócio por trás de cada um
Variações de sintaxe por banco (Oracle / SQL Server / PostgreSQL)
Exemplos de perguntas em linguagem natural que mapeiam para aquele bloco

A decisão mais crítica foi o método de chunking: delimitador semântico customizado (#----------#) em vez de tamanho fixo de tokens.

Chunking por tamanho corta o documento onde o limite de tokens cai, sem nenhuma consciência do conteúdo. Na prática, isso significa cortar uma query no meio, separar um filtro da sua regra de negócio, ou dividir o mapeamento Oracle/SQL Server em dois chunks que nunca serão recuperados juntos.

Com delimitador semântico, cada bloco é uma unidade coerente de conhecimento. É recuperado inteiro ou não é recuperado. O agente recebe contexto completo sobre aquele tipo de consulta específico, sem fragmentos de outros contextos contaminando a geração.

#----------#
## Módulo: RH | Consulta: Absenteísmo por Setor

### Query de referência (SQL Server)
SELECT RA_NOME, RA_DEPTO, COUNT(*) as FALTAS
FROM RA1010 RA
INNER JOIN RJ0010 RJ ON RA.RA_MAT = RJ.RJ_MAT
WHERE RJ.RJ_OCORR IN ('001', '002')
  AND RJ.RJ_DATA BETWEEN :data_ini AND :data_fim
GROUP BY RA_NOME, RA_DEPTO

### Variação Oracle
[...]

### Regras de negócio obrigatórias
- O campo RJ_OCORR define o tipo de ocorrência. Nunca omitir esse filtro.
- Sem o filtro de competência, a query retorna histórico completo do colaborador.
[...]

### Perguntas que mapeiam para este bloco
- Quantas faltas o setor X teve no mês passado?
- Qual a taxa de absenteísmo por departamento?
[...]
#----------#

Resultado

O impacto foi mensurável e direto:

Tempo médio por consulta: de 25 minutos para 4 minutos
Redução de ~65% nas queries com erro ou dado incorreto
Custo por request reduzido de forma significativa pelo menor uso de contexto

Os 25 minutos iniciais não eram só latência de modelo. Eram o tempo total que um analista gastava formulando a pergunta, esperando a resposta, conferindo se fazia sentido e pedindo correção quando algo estava errado. Com contexto cirúrgico e geração mais precisa, o ciclo inteiro encolheu.

O que aprendi e o que veio depois

O projeto evidenciou uma crença que carrego desde então: chunking mal feito destrói um sistema RAG independente da qualidade do modelo. Não adianta ter o melhor modelo disponível se o contexto que chega até ele está fragmentado, incompleto ou contaminado com informação irrelevante.

A POC com RAG semântico validou a abordagem e gerou os aprendizados que viabilizaram a etapa seguinte. A versão atual do Athena usa uma técnica proprietária mais eficiente, desenvolvida a partir dos problemas concretos que apareceram em produção, e não na fase de testes.

Isso é uma distinção importante: sistemas de IA em produção geram dados de falha que não existem em demo. As alucinações que aparecem quando o Protheus tem uma configuração de implantação incomum, os casos de borda de RH que nenhum benchmark cobre, são esses dados que guiam a evolução real do sistema.

Stack

Python, LangChain, LangGraph, PGVector, FastAPI, OpenAI, AWS, Docker

Bancos de dados: Oracle, SQL Server, PostgreSQL