1.Introdução

Construir uma prova de conceito com Inteligência Artificial tornou-se relativamente simples.

Um modelo pode ser carregado, conectado a um conjunto de dados e utilizado para classificar informações, gerar respostas, consultar dados, produzir relatórios ou executar algum fluxo automatizado.

Em um ambiente experimental, uma arquitetura como esta pode ser suficiente:

Interface
   ↓
Dados
   ↓
Modelo
   ↓
Processamento
   ↓
Resultado

O desafio surge quando essa solução precisa deixar de ser um experimento e passar a operar como parte de uma plataforma corporativa.

Nesse momento entram requisitos que normalmente não aparecem durante a construção do protótipo:

• autenticação;
• autorização;
• governança de dados;
• segurança;
• APIs;
• contratos;
• observabilidade;
• auditoria;
• persistência;
• escalabilidade;
• isolamento;
• controle de custos;
• versionamento;
• avaliação de modelos;
• CI/CD;
• operação;
• recuperação de falhas.

A arquitetura precisa, portanto, evoluir de um pipeline funcional de IA para um sistema de software orientado a IA.

Essa diferença é fundamental.

Um pipeline responde principalmente à pergunta:

"

Como executar determinada capacidade de IA?

Uma arquitetura de produção precisa responder:

"

Como transformar essa capacidade em um sistema seguro, governável, testável, observável e sustentável?

Este artigo apresenta uma arquitetura de referência para orientar essa evolução.

2. O problema que essa arquitetura resolve

Aplicações de IA normalmente começam concentradas em quatro responsabilidades:

Entrada
  ↓
Preparação
  ↓
Inferência
  ↓
Saída

Essa estrutura é válida.

Inclusive, a separação entre carregamento de dados, gerenciamento de modelos, execução da inferência e apresentação dos resultados representa um importante primeiro passo de engenharia.

O problema aparece quando essas responsabilidades passam a concentrar também:

regras de negócio
autorização
infraestrutura
credenciais
persistência
tratamento de erros
controle de acesso
governança
orquestração
telemetria

O resultado tende a ser uma aplicação fortemente acoplada.

Por exemplo:

UI
 ↓
carrega modelo
 ↓
busca dados
 ↓
executa inferência
 ↓
aplica regra
 ↓
grava arquivo
 ↓
gera relatório

Esse desenho pode funcionar bem para um experimento local.

Mas cria dificuldades quando precisamos:

• trocar a interface;
• disponibilizar uma API;
• mudar o modelo;
• trocar a fonte de dados;
• executar em cloud;
• processar grandes volumes;
• adicionar autenticação;
• executar tarefas assíncronas;
• auditar decisões;
• implementar múltiplos agentes;
• testar partes isoladamente.

A arquitetura de referência busca desacoplar essas responsabilidades.

3. Do pipeline experimental ao sistema de produção

A evolução normalmente passa por estágios.

Experimento
    ↓
Pipeline estruturado
    ↓
Aplicação modular
    ↓
API e contratos
    ↓
Governança e segurança
    ↓
Observabilidade e auditoria
    ↓
Automação operacional
    ↓
Plataforma de IA

Esses estágios não precisam significar diferentes sistemas.

O importante é perceber que maturidade de arquitetura não é equivalente a quantidade de serviços.

Uma solução pode permanecer como um único deploy e ainda possuir uma boa arquitetura.

O que precisa existir são limites claros entre responsabilidades.

4. Princípio arquitetural central

A principal recomendação desta arquitetura é:

"

Separar inteligência probabilística de controle determinístico.

Modelos de IA são componentes probabilísticos.

Eles são excelentes em:

• interpretação;
• classificação;
• planejamento;
• geração;
• extração;
• contextualização;
• síntese.

Mas não deveriam ser a autoridade responsável por:

• autenticação;
• autorização;
• IAM;
• controle de acesso;
• políticas corporativas;
• limites financeiros;
• integridade;
• auditoria;
• segurança;
• execução privilegiada.

A relação correta deve ser:

IA
 ↓
propõe
 ↓
Software
 ↓
valida
 ↓
autoriza
 ↓
executa

E não:

IA
 ↓
decide
 ↓
executa

Essa separação deve existir independentemente de utilizarmos classificação, RAG, agentes, SQL, ferramentas, APIs ou outros mecanismos.

5. Arquitetura de referência

Uma visão geral pode ser organizada da seguinte maneira:

┌──────────────────────────────────────┐
│          Experience Layer            │
│                                      │
│   Web / Mobile / Chat / API Client   │
└──────────────────┬───────────────────┘
                   │
                   ▼
┌──────────────────────────────────────┐
│             API / BFF                │
│                                      │
│ Auth · Validation · Rate Limit       │
│ Contracts · Streaming · Errors       │
└──────────────────┬───────────────────┘
                   │
                   ▼
┌──────────────────────────────────────┐
│          Application Layer           │
│                                      │
│ Use Cases · Coordination · Lifecycle │
└──────────────┬─────────────┬─────────┘
               │             │
               ▼             ▼
┌────────────────────┐ ┌──────────────────────┐
│    Domain Layer    │ │       AI Layer       │
│                    │ │                      │
│ Policies           │ │ Models               │
│ Rules              │ │ Prompts              │
│ Invariants         │ │ Chains               │
│ Constraints        │ │ Agents               │
└────────────────────┘ │ Workflows            │
                       │ Evaluations          │
                       └──────────┬───────────┘
                                  │
                                  ▼
┌──────────────────────────────────────────────┐
│          Integration / Data Layer            │
│                                              │
│ Data Sources · APIs · Tools · Vector Store   │
│ Warehouse · Model Providers · Storage        │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│             Infrastructure Layer             │
│                                              │
│ Compute · Identity · Secrets · Persistence   │
│ Messaging · Cache · Networking · Storage     │
└──────────────────────────────────────────────┘

Existem ainda capacidades transversais:

Security

Identity

Governance

Observability

Audit

LLMOps

Cost Management

CI/CD

Essas capacidades não pertencem exclusivamente a uma única camada.

Elas atravessam toda a arquitetura.

6. Experience Layer

A camada de experiência representa os canais utilizados pelos usuários ou sistemas consumidores.

Pode incluir:

• aplicações web;
• aplicações mobile;
• interfaces conversacionais;
• integrações;
• APIs públicas ou internas.

Sua responsabilidade é interação.

Não deve concentrar regras críticas de negócio.

Também não deve possuir acesso direto a:

bancos de dados
Data Warehouse
model providers
credenciais
service accounts
secrets
infraestrutura

O fluxo recomendado é:

Client
  ↓
API / BFF

e não:

Client
  ↓
LLM

ou

Client
  ↓
Database

7. API / BFF

A API representa a fronteira entre consumidores e o sistema.

Entre suas responsabilidades estão:

• contratos HTTP;
• autenticação;
• validação de entrada;
• rate limiting;
• idempotência;
• correlation IDs;
• versionamento;
• streaming;
• polling;
• tratamento de erros;
• paginação;
• cancelamento.

Uma API não deve se transformar em uma camada de negócio.

O papel da API é transformar:

HTTP Request

em:

Application Command

e transformar o resultado novamente em um contrato externo.

8. Application Layer

A Application Layer organiza os casos de uso.

Por exemplo:

AnalyzeData

RunInference

GenerateReport

AskQuestion

ExecuteAnalysis

GetExecution

CancelExecution

Ela define a sequência necessária para realizar uma operação.

Exemplo:

Request
   ↓
Validate Context
   ↓
Authorize
   ↓
Load Resources
   ↓
Execute AI Workflow
   ↓
Persist State
   ↓
Audit
   ↓
Return Result

A camada de aplicação conhece o processo.

Mas deve depender de abstrações para acessar:

• modelos;
• bancos;
• APIs;
• Data Warehouse;
• filas;
• persistência;
• serviços externos.

9. Domain Layer

O Domain representa o comportamento estável do sistema.

Ele concentra:

• regras;
• políticas;
• invariantes;
• restrições;
• estados permitidos;
• decisões determinísticas.

Um domínio saudável não deve depender diretamente de:

FastAPI

React

LangChain

LangGraph

SDK de cloud

SDK de banco

framework de persistência

Isso permite que regras críticas sejam testadas sem infraestrutura.

A direção desejada é:

Infrastructure
      ↓
Application
      ↓
Domain

E não o contrário.

10. AI Layer

A camada de IA concentra aquilo que realmente depende de modelos.

Por exemplo:

Model Adapters

Prompt Registry

Structured Output

Chains

Agents

Tools

Workflows

Retrieval

Evaluations

Esse isolamento possui duas vantagens principais.

Primeiro, evita que frameworks de IA contaminem todo o sistema.

Segundo, facilita trocar componentes.

Por exemplo:

Modelo A
   ↓

Application

   ↑
Modelo B

Ou:

Local Model
    ↓

Application

    ↑
Cloud Model

A aplicação não deveria precisar ser reescrita por causa da escolha de um provider.

11. Model Management

Gerenciamento de modelo deve ser tratado como uma responsabilidade explícita.

Ele pode envolver:

• carregamento;
• inicialização;
• autenticação no provider;
• configuração;
• seleção do modelo;
• versionamento;
• quantização;
• gerenciamento de dispositivo;
• fallback;
• health check.

Em inferência local:

Runtime
  ↓
Hardware Detection
  ↓
Model Loading
  ↓
Model Ready

Em inferência remota:

Runtime
  ↓
Provider Configuration
  ↓
Authentication
  ↓
Model Endpoint

A camada superior não deveria precisar conhecer essas diferenças.

O ideal é trabalhar através de uma abstração:

ModelPort

com implementações específicas.

12. Local versus Cloud

A arquitetura não deveria assumir obrigatoriamente que modelos serão executados em cloud.

Existem cenários nos quais inferência local pode ser interessante:

• privacidade;
• ausência de envio externo de dados;
• controle de custo;
• baixa latência local;
• ambientes desconectados;
• modelos especializados;
• edge computing.

Por outro lado, providers gerenciados oferecem:

• elasticidade;
• modelos maiores;
• menor gerenciamento operacional;
• integração com serviços de cloud.

Por isso:

"

Local ou cloud deve ser uma decisão de implementação, não uma decisão estrutural da aplicação.

A aplicação deveria depender de um contrato de inferência, e não do provider.

13. Data Layer

Dados também precisam ser tratados como abstrações.

Uma solução pode consumir:

arquivos

datasets

APIs

Data Warehouse

Data Lake

bancos relacionais

Vector Databases

Streams

Um DatasetLoader ou DataProvider pode encapsular essas diferenças.

Por exemplo:

Application
     ↓
Data Port
     ↓
┌────────────┬───────────────┬─────────────┐
│ File       │ Data Warehouse│ External API│
└────────────┴───────────────┴─────────────┘

Isso evita que regras de aplicação sejam acopladas a uma fonte específica.

14. Data Preparation

A preparação dos dados é uma etapa independente.

Pode envolver:

• seleção de campos;
• limpeza;
• normalização;
• validação;
• segmentação;
• enrichment;
• masking;
• chunking;
• transformação.

Em pipelines simples:

Raw Dataset
    ↓
Validation
    ↓
Preparation
    ↓
Inference

Em sistemas corporativos:

Data Source
    ↓
Governance
    ↓
Authorization
    ↓
Preparation
    ↓
AI Workflow

A IA não deve receber indiscriminadamente todos os dados disponíveis.

15. Governança do contexto

Um princípio importante para aplicações de IA é:

"

Contexto disponível não significa contexto autorizado.

O modelo deve receber apenas o conjunto mínimo de informações necessário para executar determinada tarefa.

Isso reduz:

• exposição de informações;
• custo de tokens;
• ruído;
• risco de prompt injection;
• vazamento;
• comportamento imprevisível.

O fluxo deve ser:

Available Context
      ↓
Policy
      ↓
Authorized Context
      ↓
Minimization
      ↓
LLM

16. Authorized Data Catalog

Quando uma aplicação de IA acessa plataformas corporativas de dados, não deve utilizar livremente o catálogo físico como mecanismo de autorização.

Existe uma diferença entre:

Dados existentes

e:

Dados permitidos para determinado contexto

Por isso pode existir uma camada de catálogo autorizado.

Ela define conceitualmente:

• quais recursos podem ser utilizados;
• por quais usuários;
• em quais contextos;
• sob quais restrições;
• considerando qual classificação.

O modelo deve trabalhar sobre esse universo previamente delimitado.

17. Natural Language to Data

Em soluções que transformam linguagem natural em consultas analíticas, não é recomendado permitir o fluxo:

Question
   ↓
LLM
   ↓
SQL
   ↓
Warehouse

Uma abordagem mais segura é:

Question
   ↓
LLM
   ↓
Structured Intent
   ↓
Authorization
   ↓
Query Construction
   ↓
Query Validation
   ↓
Cost Validation
   ↓
Execution

O modelo produz uma intenção.

O sistema produz a execução.

18. Structured Output

Sempre que uma saída do modelo será utilizada por outro componente do sistema, formatos estruturados devem ser preferidos.

Em vez de:

"Eu acho que deveríamos consultar a tabela X..."

preferir um contrato estruturado.

Conceitualmente:

Intent
Metrics
Dimensions
Filters
Operation
Constraints

O formato específico depende do problema.

O objetivo é tornar o resultado:

validável
tipável
testável
auditável

19. Output Parser

Modelos nem sempre respeitam perfeitamente formatos.

Por isso, a saída deve passar por parsing e validação.

Um fluxo simples pode ser:

Model Output
     ↓
Strict Parser
     ↓
Schema Validation

Dependendo do caso pode existir fallback limitado:

Strict Parser
     ↓
falhou
     ↓
Controlled Recovery

Mas retries precisam possuir limite.

Nunca utilizar loops ilimitados tentando fazer o modelo produzir uma resposta aceitável.

20. Query Security Gateway

Quando a IA influencia consultas a uma plataforma analítica, deve existir uma fronteira determinística antes da execução.

Essa camada pode ser tratada como:

Query Security Gateway

Responsabilidades possíveis:

• parsing;
• AST validation;
• allowlist;
• bloqueio de operações proibidas;
• aplicação de filtros;
• limites;
• orçamento;
• validação de escopo.

Fluxo:

Proposed Query
      ↓
SQL Parser
      ↓
AST
      ↓
Policy
      ↓
Constraints
      ↓
Approved Query

O executor deve receber apenas consultas previamente aprovadas.

21. Deny by Default

Toda operação privilegiada deve começar negada.

DEFAULT = DENY

Apenas uma decisão explícita pode permitir execução.

Esse princípio deve ser aplicado a:

• dados;
• tools;
• APIs;
• operações;
• recursos;
• credenciais;
• tenants.

22. Fail-Closed

Se o sistema não consegue determinar com segurança se uma ação pode ser executada, ela deve ser bloqueada.

Authorization unavailable
        ↓
BLOCK

Policy evaluation failed
        ↓
BLOCK

Unknown resource
        ↓
BLOCK

Não utilizar falhas de controles como justificativa para ampliar acesso.

23. Tools

Agentes normalmente interagem com sistemas através de ferramentas.

Essas ferramentas devem possuir capabilities pequenas.

Evitar:

execute_any_sql

call_any_api

read_any_file

run_shell

Preferir:

get_authorized_context

retrieve_document

execute_approved_query

get_customer_summary

A tool deve conhecer exatamente sua responsabilidade.

24. Tool Registry

Ferramentas disponíveis em produção devem ser explicitamente registradas.

Uma tool deve possuir pelo menos:

• identificação;
• finalidade;
• contrato de entrada;
• contrato de saída;
• permissões;
• timeout;
• limites;
• telemetria.

O agente não deveria descobrir arbitrariamente novas capacidades durante uma execução.

25. Agentes

Agentes devem operar dentro de limites conhecidos.

Cada agente deve possuir:

Purpose

Allowed Tools

Model

Budget

Timeout

Maximum Steps

Um agente não deve receber um cliente genérico de infraestrutura.

O correto é fornecer apenas as capabilities necessárias.

26. Workflow versus agente autônomo

Nem todo problema precisa de um agente completamente autônomo.

Quando o processo é conhecido:

Classify
   ↓
Retrieve
   ↓
Analyze
   ↓
Generate

um workflow costuma oferecer maior previsibilidade.

Agentes são mais apropriados quando realmente existe necessidade de decisão dinâmica.

A recomendação geral é:

"

Preferir workflow explícito quando o processo puder ser modelado previamente.

27. Orquestração

Frameworks de orquestração podem ser utilizados para organizar etapas de IA.

Um workflow pode conter:

START
  ↓
validate_input
  ↓
authorize
  ↓
load_context
  ↓
plan
  ↓
execute_model
  ↓
validate_output
  ↓
persist_result
  ↓
audit
  ↓
END

Estados alternativos também devem existir:

BLOCKED

FAILED

CANCELLED

WAITING_APPROVAL

Isso torna o comportamento observável e testável.

28. Papel de frameworks de composição de IA

Frameworks de composição podem ser utilizados para:

• integração com modelos;
• prompts;
• structured outputs;
• parsers;
• retrievers;
• chains;
• callbacks.

Eles não deveriam se tornar a arquitetura da aplicação.

Uma aplicação saudável deve continuar existindo mesmo se o framework for substituído.

29. Papel de frameworks de grafos

Frameworks orientados a grafos são úteis quando existem:

• workflows stateful;
• roteamento condicional;
• checkpoint;
• retomada;
• human-in-the-loop;
• streaming;
• cancelamento;
• retry controlado.

Porém:

"

O grafo deve executar o caso de uso, não representar todo o domínio do sistema.

30. Estado

O estado de uma execução deve conter apenas aquilo que precisa sobreviver entre etapas.

Por exemplo:

execution_id
current_state
context_reference
model_version
result_reference
status
timestamps

Evitar manter:

gigabytes de resultados

credenciais

tokens

dados sensíveis desnecessários

objetos gigantes em memória

Estado também é uma superfície de segurança.

31. Persistência

Resultados relevantes precisam sobreviver ao processo da aplicação.

Podem existir diferentes formas de persistência para:

execution state

audit

business results

reports

checkpoints

metadata

A memória local da aplicação não deve ser utilizada como fonte durável de estado.

Isso permite:

restart

autoscaling

failover

resume

32. Resultados volumosos

Um erro recorrente é materializar grandes conjuntos de dados dentro da aplicação.

Evitar:

Warehouse
   ↓
3 milhões de linhas
   ↓
DataFrame
   ↓
Application Memory

Preferir:

Warehouse
   ↓
Aggregation
   ↓
Pagination
   ↓
Result Reference

O processamento pesado deve permanecer no sistema projetado para processá-lo.

33. Processamento em lote

Nem todo workload de IA precisa ser síncrono.

Classificação de milhares ou milhões de registros pode exigir:

Job
 ↓
Queue
 ↓
Worker
 ↓
Inference
 ↓
Progress
 ↓
Result

A interface acompanha a execução por:

• polling;
• eventos;
• streaming;
• callbacks.

Isso evita manter requisições HTTP abertas durante processamentos longos.

34. Streaming

Alguns casos se beneficiam de streaming.

Por exemplo:

LLM tokens

workflow status

progress events

partial results

Mas streaming não deve ser utilizado para transferir grandes datasets indiscriminadamente.

O objetivo é melhorar experiência e observabilidade da execução.

35. Human-in-the-Loop

Algumas decisões podem exigir intervenção humana.

Exemplos:

• operações de alto impacto;
• acesso sensível;
• consultas caras;
• confiança baixa;
• resultados ambíguos.

Fluxo:

AI Decision
    ↓
Policy
    ↓
Approval Required
    ↓
WAITING_APPROVAL
    ↓
Human
    ↓
Resume / Reject

A aprovação precisa fazer parte do workflow e da auditoria.

36. Segurança contra Prompt Injection

Prompt injection não chega apenas através da pergunta do usuário.

Ela pode estar presente em:

• documentos;
• registros;
• APIs;
• banco de dados;
• metadata;
• conteúdo recuperado.

Portanto:

"

Todo conteúdo externo deve ser considerado dado não confiável para fins de instrução.

Conteúdo recuperado não pode modificar:

system policies
tool permissions
authorization
security constraints
budgets

37. Secrets

Credenciais nunca deveriam existir diretamente em:

código

frontend

notebook versionado

repositório

prompt

Preferir:

Runtime Identity

Workload Identity

Secret Manager

A IA nunca precisa conhecer a credencial.

Ela precisa apenas da capability fornecida pelo sistema.

38. Observabilidade

Aplicações de IA precisam de observabilidade tradicional e observabilidade específica de IA.

Um trace pode seguir:

HTTP Request
      ↓
Application Use Case
      ↓
AI Workflow
      ↓
Model Invocation
      ↓
Tool Call
      ↓
Data Operation

Informações importantes:

latência

erros

modelo utilizado

versão do prompt

tokens

retries

custo

tool calls

workflow state

volume processado

39. Auditoria

Auditoria deve responder perguntas diferentes de observabilidade.

Por exemplo:

Quem solicitou?

Quando?

Qual ação?

Qual recurso?

Qual política autorizou?

Qual modelo participou?

Qual operação foi executada?

Qual resultado foi produzido?

Auditoria deve ser suficiente para reconstruir decisões relevantes.

Sem registrar conteúdo sensível desnecessariamente.

40. LLMOps

Modelos e prompts precisam ser tratados como artefatos versionados.

A plataforma deve conhecer:

model_version

prompt_version

pipeline_version

evaluation_version

Uma alteração de prompt pode alterar significativamente o comportamento da aplicação.

Por isso ela precisa ser tratada como mudança de software.

41. Avaliações

Testes tradicionais não são suficientes para sistemas probabilísticos.

Também precisamos de avaliações.

Exemplos:

classification accuracy

precision

recall

groundedness

faithfulness

tool selection

context selection

structured-output validity

Os conjuntos de avaliação precisam ser versionados.

42. Baseline

Antes de alterar:

modelo

prompt

retriever

workflow

parâmetros

é importante possuir um baseline.

Current Version
     ↓
Evaluation
     ↓
Baseline

New Version
     ↓
Evaluation
     ↓
Comparison

Somente então devemos promover uma nova versão.

43. Retry

Retries devem ser classificados.

Um erro transitório pode receber retry:

timeout

rate limit

temporary provider failure

Um erro determinístico não deveria:

authorization denied

invalid input

policy violation

budget exceeded

Nunca enviar automaticamente um erro de permissão ao modelo para tentar encontrar outra forma de acesso.

44. Resiliência

Integrações externas devem possuir:

timeouts

bounded retries

backoff

circuit breaker

cancellation

Um modelo lento não pode consumir indefinidamente workers do backend.

45. Controle de custo

Custos podem vir de diferentes fontes:

LLM Tokens

GPU

Warehouse

Storage

Vector Database

Network

Workers

A arquitetura deve tratar custo como métrica de primeira classe.

Por exemplo:

cost per request

cost per user

cost per workflow

cost per model

cost per tenant

46. API síncrona versus execução assíncrona

Operações rápidas podem ser síncronas:

POST
 ↓
Process
 ↓
200 Result

Processamentos longos devem preferir:

POST
 ↓
202 + execution_id

Depois:

GET /executions/{id}

ou streaming de eventos.

47. Monólito modular como ponto de partida

Uma arquitetura profissional não precisa começar com microserviços.

Um desenho adequado pode ser:

Frontend
   +
Backend Modular

Com módulos internos:

api/

application/

domain/

ai/

infrastructure/

config/

A vantagem é possuir limites arquiteturais sem introduzir imediatamente:

• rede;
• service discovery;
• tracing distribuído;
• múltiplos deploys;
• contratos remotos;
• consistência distribuída.

48. Quando separar serviços

Um módulo deve ser extraído quando existir evidência.

Por exemplo:

Scale

Ownership

Security Boundary

Blast Radius

Deployment Frequency

Availability

Regulatory Isolation

Não porque:

"é IA"

ou

"microserviços são mais modernos"

49. Arquitetura de dependências

A direção recomendada é:

API
 ↓
Application
 ↓
Domain

Enquanto:

AI
Data
Persistence
Model Providers
External APIs

implementam interfaces utilizadas pela aplicação.

Assim:

Application
      ↓
     Port
      ↑
Infrastructure Adapter

50. Estrutura conceitual

Uma aplicação desse tipo pode utilizar uma organização semelhante:

apps/
 ├── web/
 │
 └── api/
      └── src/
           ├── api/
           ├── application/
           ├── domain/
           ├── ai/
           ├── infrastructure/
           └── config/

evals/

infra/

docs/

tests/

A estrutura física pode variar.

O importante são as fronteiras de responsabilidade.

51. Estratégia de testes

Domain

Testar:

policies
rules
constraints
budgets

Application

Testar:

use cases
orchestration
failure paths
idempotency

AI

Testar:

structured outputs
prompts
model behavior
agent decisions

Data

Testar:

queries
contracts
pagination
authorization

API

Testar:

authentication
authorization
input validation
error contracts

Security

Testar:

prompt injection
tool abuse
data exfiltration
tenant isolation

Performance

Testar:

load
concurrency
latency
memory
cost

52. Anti-patterns

Interface acoplada ao modelo

UI → Model

Modelo acessando diretamente banco de dados

LLM → Database

Modelo possuindo credenciais

SQL livre exposto ao agente

Autorização implementada apenas em prompt

Dados existentes tratados como dados autorizados

Pipeline inteiro em uma única classe

Regra de negócio implementada dentro de nodes de IA

Estado apenas em memória

DataFrames gigantes armazenados no workflow

Retries ilimitados

Logs contendo PII ou secrets

Microserviços prematuros

53. Fluxo de referência

Uma execução típica pode seguir:

User Request
      ↓
Authentication
      ↓
API Validation
      ↓
Application Use Case
      ↓
Authorization
      ↓
Authorized Context
      ↓
AI Planning
      ↓
Structured Output
      ↓
Deterministic Validation
      ↓
Tool / Data Execution
      ↓
Result Validation
      ↓
AI Synthesis
      ↓
Persistence
      ↓
Audit
      ↓
Response

Observe que a IA participa do processo.

Ela não controla todo o processo.

54. Evolução recomendada

Para soluções que atualmente existem como notebooks ou pipelines experimentais, uma evolução segura pode seguir estas etapas.

Fase 1 — Modularização

Separar:

UI
Model
Data
Pipeline
Reporting

Fase 2 — Contratos

Introduzir:

schemas
ports
interfaces
configuration
dependency injection

Fase 3 — Application e Domain

Extrair:

use cases
business rules
policies

Fase 4 — API

Introduzir:

authentication
authorization
contracts
rate limits
error handling

Fase 5 — Orquestração de IA

Introduzir quando necessário:

structured outputs
chains
workflows
agents
tools

Fase 6 — Persistência e Execuções

Introduzir:

execution lifecycle
checkpoints
results
audit

Fase 7 — Observabilidade

Adicionar:

logs
metrics
traces
LLM telemetry
cost

Fase 8 — Produção

Adicionar:

containers
CI/CD
secrets
IaC
rollback
monitoring

Fase 9 — Hardening

Executar:

security testing
prompt injection testing
load testing
evaluation regression
failure testing

55. Checklist de referência

Antes de promover uma solução de IA para produção:

• responsabilidades estão modularizadas;
• domínio não depende de frameworks de IA;
• interface não acessa infraestrutura diretamente;
• autenticação está implementada;
• autorização ocorre no backend;
• modelo não possui credenciais;
• tools possuem capabilities restritas;
• entradas possuem validação;
• saídas do modelo possuem validação;
• retries possuem limites;
• timeouts estão definidos;
• cancelamento é suportado quando necessário;
• execução longa é assíncrona;
• estado crítico possui persistência;
• dados sensíveis são minimizados;
• logs não armazenam secrets;
• auditoria está implementada;
• métricas de IA estão disponíveis;
• custos são observáveis;
• prompts são versionados;
• modelos são versionados;
• avaliações possuem baseline;
• testes de segurança existem;
• testes de carga existem;
• deploy e rollback estão definidos.

56. Princípios para os times

Como referência arquitetural, os seguintes princípios devem ser considerados.

1. IA é uma capacidade do sistema, não o sistema inteiro.

2. Modelos devem ficar atrás de abstrações.

3. Dados devem ficar atrás de abstrações.

4. Frameworks de IA não devem determinar a arquitetura da aplicação.

5. O LLM propõe; software determinístico controla a execução.

6. Segurança não deve depender de prompts.

7. Agentes devem possuir capabilities mínimas.

8. Credenciais nunca devem chegar ao agente.

9. Todo conteúdo externo deve ser considerado não confiável.

10. Structured output deve ser utilizado quando uma resposta alimenta outro componente.

11. Workflows explícitos devem ser preferidos quando o processo é conhecido.

12. Agentes autônomos devem existir somente quando a autonomia realmente agrega valor.

13. Estado deve ser mínimo, persistível e seguro.

14. Grandes volumes devem permanecer na plataforma responsável por processá-los.

15. Modelos, prompts e datasets de avaliação devem possuir versão.

16. IA precisa de avaliações além de testes tradicionais.

17. Observabilidade deve acompanhar a execução ponta a ponta.

18. Auditoria deve registrar decisões relevantes.

19. Custos devem ser observáveis e limitáveis.

20. Monólitos modulares são uma opção válida para começar.

21. Microserviços devem surgir por necessidade operacional.

22. A arquitetura deve permitir trocar modelos, dados e infraestrutura sem reescrever o domínio.

57. Conclusão

A transição entre um experimento de IA e um sistema de produção não acontece simplesmente adicionando uma interface, uma API ou um deploy em cloud.

Ela acontece quando deixamos de pensar apenas no modelo e começamos a pensar no sistema ao redor dele.

Um pipeline experimental pode ser resumido como:

Data
 ↓
Model
 ↓
Result

Uma plataforma de produção precisa considerar:

User
 ↓
Experience
 ↓
API
 ↓
Application
 ↓
Domain
 ↓
AI
 ↓
Data / Tools
 ↓
Infrastructure

E transversalmente:

Security
Governance
Observability
Audit
LLMOps
Cost

A principal mudança arquitetural está na distribuição de responsabilidades.

A Inteligência Artificial deve permanecer responsável por aquilo que faz melhor:

interpretar

classificar

planejar

gerar

contextualizar

sintetizar

Enquanto software determinístico permanece responsável por:

autenticar

autorizar

validar

limitar

executar

persistir

auditar

Essa separação permite construir sistemas onde modelos podem evoluir rapidamente sem comprometer a estabilidade da plataforma.

Também permite que diferentes times — Software Engineering, Data Engineering, AI Engineering, Platform e Security — trabalhem sobre fronteiras claras.

A arquitetura deixa de estar centrada no modelo.

Ela passa a estar centrada na capacidade do sistema.

E esse é o passo necessário para transformar pipelines e experimentos de Inteligência Artificial em plataformas corporativas realmente preparadas para produção.