Arquitetura Modular com IA Generativa: Tratando Inteligência como Capacidade, Não como Dependência

Existe um momento específico na vida de um sistema que incorpora IA Generativa em que a dívida arquitetural se torna insuportável. Não é quando o primeiro bug aparece. É quando alguém pergunta: "Qual prompt estava em produção quando isso aconteceu?" e ninguém sabe responder.

O Problema Que Ninguém Nomeia

Chamo de AI Spaghetti o estado em que a lógica de IA está distribuída caoticamente pela base de código: chamadas de modelo dentro de controllers, montagem de prompts concatenando strings em helpers, lógica de retrieval misturada com regras de negócio, e zero separação entre o que o sistema quer fazer e como a IA executa isso.

Esse estado não nasce de negligência. Nasce de velocidade e de uma ilusão específica que a IA Generativa cria: a de que integrar é trivial. E é, no início. Uma chamada de API, uma resposta, valor entregue. O problema é que sistemas não são protótipos, e a maioria dos times percebe isso tarde demais.

O custo real do AI Spaghetti não aparece nos testes. Aparece em produção, meses depois, quando você precisa trocar de provider e descobre que isso exige cirurgia em dezenas de arquivos. Quando precisa investigar um incidente e não consegue reconstruir o contexto da chamada. Quando tenta medir o custo real de operação e não tem granularidade nenhuma. Quando escala a equipe e percebe que ninguém entende o fluxo completo.

A ironia é que a solução não requer nenhuma tecnologia nova. Requer a aplicação de princípios arquiteturais já bem estabelecidos aplicados a um domínio que a indústria ainda está aprendendo a tratar com seriedade.

O Princípio Fundamental: IA como Capacidade

A premissa central de uma boa arquitetura de IA é deceptivamente simples:

"

IA Generativa é uma capacidade, não uma implementação.

Assim como "persistência" é uma capacidade que pode ser satisfeita por Postgres, DynamoDB ou Redis e você a abstrai atrás de um repositório inteligência generativa é uma capacidade que pode ser satisfeita por OpenAI, Anthropic, modelos locais, ou um ensemble rodando em paralelo.

Quando você trata IA como implementação, sua lógica de negócio sabe demais. Sabe qual SDK usar, qual modelo chamar, como formatar a requisição, como interpretar a resposta. Essa promiscuidade cria acoplamento que cobra seu preço com juros.

Quando você trata IA como capacidade, a lógica de negócio declara o que precisa "quero que alguém avalie se este texto é relevante para esta pergunta" e o sistema de IA cumpre esse contrato sem expor os detalhes de como.

Esse princípio tem nome na literatura de design: é a Inversão de Dependência aplicada ao domínio de IA. E sua expressão arquitetural mais natural são os Ports & Adapters a Arquitetura Hexagonal.

A Anatomia de Uma Camada de IA Bem Projetada

Uma camada de IA bem desenhada tem fronteiras claras entre quatro responsabilidades distintas. Confundi-las é a raiz da maioria dos problemas.

Os contratos definem o que o sistema de IA precisa entregar, sem revelar como. Um contrato de inferência declara que dado um prompt, espera-se uma resposta com uso de tokens e metadados de rastreabilidade. Um contrato de embedding declara que dado um texto, espera-se um vetor. Um contrato de retrieval declara que dado um vetor, espera-se documentos rankeados por relevância. Esses contratos pertencem ao domínio da aplicação não à infraestrutura.

Os adaptadores são implementações concretas desses contratos. O adapter da Anthropic sabe como chamar a API do Claude. O da OpenAI sabe como chamar o GPT. O Ollama sabe como chamar modelos locais. Para a aplicação, todos são intercambiáveis cumprem o mesmo contrato.

O serviço de orquestração coordena os contratos para executar fluxos complexos. Um pipeline de RAG, por exemplo, orquestra embedding → retrieval → montagem de contexto → inferência → validação de resposta. Esse serviço conhece os contratos, não os adaptadores.

A infraestrutura de IA provê capacidades transversais: gestão de prompts, circuit breakers, telemetria, cache semântico, gestão de custos. Ela não executa lógica de negócio ela garante que a camada de IA opere com confiabilidade.

O resultado dessa separação é um sistema onde trocar de GPT-4o para Claude Opus é uma mudança de configuração, não uma refatoração. Onde adicionar um novo provider leva horas, não dias. Onde a testabilidade é natural porque você substitui contratos, não SDKs.

Gerenciamento de Prompts: A Disciplina Ignorada

Se há um único aspecto onde a maioria dos sistemas de IA em produção falha sistematicamente, é o gerenciamento de prompts.

Prompts são artefatos de primeira classe. Eles determinam o comportamento do sistema tanto quanto qualquer linha de código. Mas enquanto código tem versionamento, revisão, histórico e rastreabilidade, prompts frequentemente vivem como strings literais enterradas em arquivos, copiadas entre ambientes sem controle, modificadas diretamente em produção por conveniência.

O problema se torna evidente quando algo dá errado. Um incidente em produção exige resposta às seguintes perguntas: qual versão do prompt estava ativa? Quando foi a última mudança? Quem aprovou? Qual era o comportamento antes? Sistemas sem controle de prompt não conseguem responder nenhuma delas.

A solução é tratar prompts com a mesma governança aplicada a código e configuração. Isso significa versionamento com semântica clara prompts têm versões que evoluem com significado explícito. Significa histórico de mudanças e rastreabilidade de autoria. Significa promoção entre ambientes com os mesmos controles aplicados a deploys.

Há ainda uma dimensão frequentemente negligenciada: prompts precisam de testes. Não apenas validação manual de "parece bom", mas suítes de avaliação que verificam se a versão atual continua satisfazendo os comportamentos esperados casos de borda, cenários de falha, instruções de fronteira. Tudo isso precisa estar codificado como expectativas verificáveis.

O corolário inevitável é que mudanças de prompt precisam passar por processo de revisão. Assim como nenhum engenheiro sobe código em produção sem review, nenhum prompt deveria ser promovido sem avaliação sistemática do impacto na qualidade das respostas.

RAG Como Arquitetura, Não Como Feature

Retrieval-Augmented Generation virou buzzword antes de virar disciplina. A maioria das implementações trata RAG como uma feature um conjunto de chamadas encadeadas que "busca documentos e manda pro modelo". Isso funciona em demos. Em produção, fragmenta.

RAG bem arquitetado é um pipeline com estágios independentes, cada um com responsabilidades claras e pontos de intervenção explícitos.

A fase de ingestão processamento, chunking e indexação de documentos precisa ser completamente separada da fase de serving. Essa separação é estratégica: a estratégia de chunking tem impacto direto na qualidade do retrieval, e você precisa iterar sobre ela sem afetar o sistema em produção. Hierarquia de chunks, sobreposição, enriquecimento com metadados essas decisões merecem experimentação controlada.

A fase de retrieval tem mais nuances do que aparenta. Busca vetorial pura frequentemente não é suficiente. Sistemas robustos combinam busca semântica com busca por palavras-chave (hybrid search), aplicam reranking para refinar os resultados iniciais, e filtram por metadados para restringir o espaço de busca. Cada um desses estágios é um ponto de otimização independente.

A montagem do contexto é onde a maioria dos sistemas desperdiça dinheiro e qualidade simultaneamente. Enviar todos os documentos recuperados indiscriminadamente para o modelo é um antipadrão. Janelas de contexto têm custo cada token enviado é um token pago e documentos marginalmente relevantes frequentemente prejudicam mais do que ajudam, diluindo a atenção do modelo sobre o que realmente importa. Um assembler bem projetado orquestra seleção dentro de um orçamento de tokens, formatação que favorece a compreensão do modelo, e compressão de histórico de conversa quando necessário.

A validação da resposta fecha o loop. A resposta está fundamentada no contexto fornecido? O modelo alucinou informações? O conteúdo satisfaz critérios de segurança? Essas verificações não são opcionais em sistemas que chegam a usuários reais.

Resiliência: O Que Ninguém Planeja Até o Primeiro Incidente

APIs de LLM têm características que tornam resiliência não apenas desejável, mas obrigatória. Latência altamente variável, onde o P99 pode ser dez vezes o P50. Rate limits que chegam sem aviso em períodos de carga. Falhas parciais onde o modelo retorna mas com qualidade degradada. Interrupções de provider que, sem fallback, tornam-se interrupções do seu serviço.

O Circuit Breaker é o primeiro instrumento de resiliência a implementar. Ele monitora falhas consecutivas e, ao detectar degradação, para de enviar requisições que provavelmente falharão protegendo o sistema de cascata de erros e dando ao provider tempo para se recuperar.

Mas Circuit Breaker isolado não é suficiente. Sistemas críticos precisam de fallback entre providers. Um router de modelos que tenta o provider primário, detecta falha, e automaticamente direciona para um provider secundário transforma uma indisponibilidade de vendor em degradação imperceptível para o usuário. A simetria de contratos nos adapters é o que torna isso possível sem lógica adicional.

Timeouts agressivos são tão importantes quanto fallbacks, e frequentemente mais negligenciados. Uma chamada de LLM sem timeout pode aguardar indefinidamente, consumindo recursos e degradando a experiência sem nunca falhar explicitamente. Todo sistema de IA precisa de timeouts por padrão.

Retry com backoff exponencial resolve falhas transitórias. Mas retry sem circuit breaker pode piorar uma situação já degradada. Os dois trabalham juntos: retry para falhas isoladas, circuit breaker para falhas sistêmicas.

Observabilidade: As Três Dimensões Que Importam

Observabilidade em sistemas tradicionais vive em torno dos quatro golden signals: latência, tráfego, erros e saturação. Sistemas de IA precisam dessas dimensões e de mais três camadas específicas.

Métricas operacionais são o que o SRE monitora. Latência por provider e por modelo porque P95 de inferência é um SLO que você precisa honrar. Taxa de erros segmentada por tipo rate limit, timeout, content filter, erro de rede têm causas e soluções diferentes. Volume de tokens consumidos por feature porque custo em sistemas de IA é proporcional ao consumo, e sem granularidade você voa cego no orçamento.

Métricas de qualidade são o que o produto monitora. Taxa de respostas fundamentadas em evidências especialmente em RAG, onde alucinação é o risco principal. Score médio de relevância dos documentos recuperados se está caindo, sua base de conhecimento pode estar desatualizada ou seu índice pode estar degradando. Feedback explícito do usuário ruidoso, mas insubstituível. Distribuição de tamanho das respostas respostas sistematicamente muito curtas ou muito longas são sintomas de problemas no prompt.

Métricas de governança são o que compliance monitora. Distribuição de versões de prompt em produção você precisa saber se uma versão antiga ainda está servindo tráfego. Taxa de acionamento de content filters picos indicam tentativas de abuso. Rastreabilidade de chamadas a capacidade de reconstruir completamente o contexto de qualquer interação a partir de um correlation ID.

A distinção entre essas camadas importa porque têm audiências e cadências diferentes. Métricas operacionais são monitoradas em tempo real por alertas. Métricas de qualidade são analisadas em dashboards semanais. Métricas de governança são auditadas periodicamente e sob demanda em investigações.

Testabilidade: A Consequência Natural de Bons Contratos

Uma arquitetura bem projetada é, quase por definição, testável. Quando a lógica de negócio depende de contratos e não de implementações, testá-la não requer chamadas reais para APIs de LLM requer apenas substitutos determinísticos dos contratos.

Isso resolve um problema que paralisa muitos times: como testar fluxos de IA sem pagar por tokens, sem depender de disponibilidade de API, sem flakiness por variabilidade de resposta? A resposta é que você não testa a IA você testa a lógica ao redor da IA.

A pirâmide de testes para sistemas de IA tem três níveis com propósitos distintos.

Testes unitários cobrem componentes de lógica pura: o assembler de contexto que respeita orçamentos de tokens, o renderizador de prompt que interpola variáveis corretamente, o estimador de custo. Nenhum desses testes precisa de LLM.

Testes de integração cobrem a orquestração do pipeline completo, com substitutos determinísticos nos contratos. O fluxo de RAG pode ser testado com embeddings fixos, documentos pré-definidos e resposta de LLM substituída. Você valida que a orquestração está correta, que os dados fluem entre os estágios como esperado, que erros são propagados adequadamente.

Testes de avaliação cobrem qualidade semântica e aqui LLMs são inevitáveis. A técnica de LLM-as-Judge automatiza a avaliação de respostas contra critérios definidos: a resposta está fundamentada no contexto? É relevante para a pergunta? Um modelo avaliador, operando com temperatura zero para determinismo, produz scores que podem ser incorporados ao pipeline de CI/CD. Se a média de fundamentação cai abaixo de um threshold após uma mudança de prompt, o deployment é bloqueado.

Testes unitários e de integração rodam em cada commit, em segundos, sem custo. Testes de avaliação rodam em pull requests significativos, em minutos, com custo controlado. Essa separação é o que torna a abordagem prática em escala.

Multi-Agente: Quando Um Modelo Não É Suficiente

Sistemas de agentes múltiplos estão emergindo como padrão para tarefas que excedem a capacidade de um único LLM em uma única chamada. A arquitetura é poderosa e por isso mesmo merece atenção especial às suas armadilhas.

O padrão central é a separação entre orquestrador e executores. O orquestrador recebe a tarefa de alto nível e decide a sequência de ações necessárias. Os executores são especializados um agente que pesquisa, um que escreve, um que valida, um que interage com APIs externas. Cada executor tem escopo limitado e bem definido.

Essa especialização tem uma vantagem frequentemente subestimada: modelos menores e mais baratos podem executar tarefas especializadas com qualidade comparável a modelos maiores executando tarefas genéricas. O orquestrador pode ser o único componente que exige o modelo mais capaz.

As armadilhas de sistemas multi-agente são específicas. Propagação de erros é a mais insidiosa um agente que produz output incorreto em um estágio inicial contamina todos os estágios subsequentes, e o sistema frequentemente continua executando com convicção crescente na direção errada. Checkpoints de validação entre estágios são o mecanismo de contenção.

Loops infinitos emergem quando o orquestrador não tem limite explícito de iterações. Todo sistema de agentes precisa de um budget de iterações hard-coded. Rastreabilidade em sistemas multi-agente é ordens de magnitude mais complexa do que em agente único um correlation ID precisa traversar todos os agentes, e cada decisão do orquestrador precisa ser logada com seu raciocínio.

Deployment: Prompts São Código

Uma mudança de prompt em produção tem o mesmo potencial de impacto que uma mudança de código. Ela pode silenciosamente degradar a qualidade das respostas, introduzir vieses, ou alterar comportamentos que usuários dependem. Mas na maioria dos sistemas, prompts são tratados com muito menos rigor.

A estratégia de canary release, familiar em deploys de código, se aplica diretamente a prompts. Uma nova versão começa servindo uma fração pequena do tráfego. Métricas de qualidade são comparadas entre a versão atual e a candidata em tempo real. Se a candidata demonstra melhora ou paridade, o rollout continua. Se demonstra degradação, o rollback é automático.

O que torna isso tecnicamente viável é o prompt registry. Quando cada request carrega o identificador da versão do prompt que o processou, comparar versões torna-se trivial você segmenta métricas por versão e a comparação emerge dos dados.

A mesma disciplina se aplica a mudanças de modelo. Migrar de uma versão para outra ou de um provider para outro é uma mudança de comportamento do sistema, não apenas de infraestrutura. Requer o mesmo processo de avaliação, o mesmo canary cauteloso, e a mesma capacidade de rollback rápido.

Governança e IA Responsável

Sistemas de IA em produção têm responsabilidades que sistemas tradicionais não têm, ou têm em menor escala.

Alucinação é uma falha específica da IA generativa sem análogo preciso em software determinístico. Um sistema que apresenta informações falsas com a mesma confiança que apresenta informações verdadeiras cria riscos que vão do reputacional ao legal. Guardrails de saída verificações que validam a resposta antes de enviá-la ao usuário são a linha de defesa aqui. Não eliminam alucinação, mas contêm seus efeitos.

Vazamento de informação é um risco em qualquer sistema RAG que indexa documentos sensíveis. Sem controle de acesso no nível do retrieval, um usuário pode obter informações que não deveria ter acesso não porque a IA cometeu um erro moral, mas porque o sistema não implementou os controles adequados. Namespace isolation no vector store, filtros por permissão de usuário, e validação de autorização antes do retrieval são controles não-negociáveis em sistemas corporativos.

Injeção de prompt ataques onde conteúdo malicioso nos documentos recuperados tenta manipular o comportamento do modelo é uma superfície de ataque específica de sistemas RAG. Separação clara entre instrução e dados no template do prompt, e monitoramento de comportamentos anômalos são as defesas disponíveis.

A documentação de modelos e pipelines não é burocracia. É o mecanismo que permite ao time, auditores e stakeholders entender o comportamento esperado do sistema, suas limitações conhecidas e os vieses identificados.

O Que Separa Arquitetura de Brinquedo de Arquitetura de Produção

Depois de construir e revisar muitos sistemas de IA, identifico cinco dimensões que distinguem consistentemente sistemas robustos de sistemas frágeis.

Contratos explícitos separam o que o sistema quer da IA de como a IA entrega. Sistemas robustos têm interfaces bem definidas. Sistemas frágeis têm dependências diretas de SDK espalhadas pelo código.

Rastreabilidade end-to-end permite reconstruir o contexto completo de qualquer interação. Sistemas robustos têm correlation IDs, versionamento de prompts, e logging estruturado de decisões. Sistemas frágeis não conseguem responder "o que aconteceu nesta chamada específica?"

Qualidade como métrica contínua, não como verificação pontual. Sistemas robustos medem fundamentação, relevância e segurança em produção, continuamente. Sistemas frágeis dependem de feedback reativo de usuários.

Resiliência por design, não como afterthought. Sistemas robustos funcionam de forma degradada quando providers falham. Sistemas frágeis propagam falhas de vendor diretamente para o usuário.

Governança de prompt com o mesmo rigor aplicado a código. Sistemas robustos têm histórico de mudanças, processo de aprovação, e capacidade de rollback. Sistemas frágeis têm strings literais modificadas diretamente em produção.

Por Onde Começar

A refatoração perfeita não existe. O que existe é uma sequência de mudanças que reduz risco progressivamente sem paralisar o time.

O ponto de partida de maior impacto é extrair um contrato de inferência. Criar uma interface que encapsula chamadas de LLM sem mudar nada mais imediatamente torna o código testável e prepara o terreno para tudo que vem depois. Sem nenhuma mudança de comportamento em produção.

O segundo passo é implementar o prompt registry, mesmo que inicialmente seja apenas um repositório de arquivos com versionamento em Git. Você ganha rastreabilidade de qual prompt está em produção e histórico de mudanças sem complexidade operacional.

O terceiro passo é adicionar telemetria básica: tokens consumidos por feature, latência de inferência, taxa de erros por provider. Esses dados iluminam o sistema de uma forma que muda permanentemente como o time toma decisões.

O restante circuit breaker, testes de avaliação, gestão de contexto, guardrails pode ser adicionado iterativamente, priorizando pela dor mais imediata.

O sistema de IA ideal não é o mais sofisticado. É o que permite ao seu time iterar com confiança mudar prompts sem medo, trocar providers sem reescrever, escalar sem surpresas. Esse é o norte.