Plataforma de agentes de IA para empresas: o design da arquitetura

O que é e em que estado está

A plataforma de agentes de IA para empresas está em construção, na fase 0: arquitetura. Ainda não há código publicado. Esta página descreve o design que defini, não um produto que se possa usar hoje.

O design está documentado com um modelo C4, um diagrama de sequência e 10 ADRs. O diagrama de arquitetura completo pode ser aberto em tamanho completo mais abaixo.

O problema que resolve

A informação de uma empresa está espalhada entre planilhas de Excel, bancos de dados, APIs e documentos. A plataforma se propõe a conectar essas fontes e responder perguntas em linguagem natural indicando, em cada resposta, de onde sai cada número.

O que a pessoa recebe no chat são respostas com suas fontes, gráficos e dashboards, e relatórios em PDF.

Arquitetura

São quatro peças: um serviço de ingestão, um banco PostgreSQL com pgvector, um serviço de agentes e uma aplicação web. A camada transversal adiciona o LLM via LangChain, traces e custos com Langfuse, e avaliações sobre um conjunto de perguntas.

• Stack previsto: Python, LangGraph, LangChain, FastAPI, PostgreSQL com pgvector, Langfuse, Next.js e Docker.
• Deploy previsto: Docker Compose no servidor próprio do cliente (on-prem).
• Aplicação web: um frontend de chat em Next.js, um API gateway em FastAPI, autenticação e RBAC com um JWT que leva o tenant_id, e usuários com papéis e permissões.

Fontes de dados e ingestão

As fontes estruturadas são APIs REST, webhooks, bancos externos (MySQL e SQL Server), Excel e CSV, e JSON. As não estruturadas são PDF, Word, digitalizações e imagens que precisam de OCR, e e-mail, TXT e MD.

• Conectores com sincronização incremental.
• Workers sobre Redis e Celery, com novas tentativas, backoff e uma fila de jobs com falha.
• Mapeamento de colunas para o esquema, usando um LLM opcional apenas nos campos ambíguos.
• Validação com Pydantic.
• Parser e OCR com PyMuPDF e Tesseract, seguidos de chunking e embeddings.
• Upload de documentos.

A parte de IA: o serviço de agentes

O serviço de agentes expõe duas ferramentas do LangChain. A SQL Tool é o único acesso às tabelas. A Retrieval Tool busca os top-k trechos, sempre dentro de um tenant.

Sobre elas há um grafo de estados do LangGraph: um orquestrador encaminha cada pergunta ao agente de SQL, ao agente de relatórios (gráficos e PDF) ou ao agente de RAG. A memória usa um checkpointer.

Confiabilidade e segurança previstas

• A SQL Tool é somente leitura: lista permitida, SQL validado, timeout, limite de linhas e RLS.
• As tabelas levam RLS por tenant_id, e a Retrieval Tool também busca por tenant.
• Um guardrail de entrada contra prompt injection e um guardrail de saída que valida e cita.
• Os documentos são guardados com hash e versões.
• O Langfuse registra traces e custos, e o sistema é avaliado sobre um conjunto de perguntas.

O que está definido e o que não está

• Definido: a arquitetura, documentada com um modelo C4, um diagrama de sequência e 10 ADRs.
• Ainda não existe: o código. Não há repositório público, não há demo e não há métricas, porque não há nada a medir.
• Tudo o que está acima é design. Quando houver uma primeira versão funcionando, esta página será atualizada com o que tiver sido medido.