Manual de Arquitetura de IA LZR

Versão 1.0 — 2026-06-20. Define como inteligência artificial é construída dentro dos produtos LZR — da escolha de abordagem à avaliação, segurança e observabilidade.

O que este manual responde: como construo IA dentro do produto de forma profissional. Tudo que é "como construo código certo" mora no Manual de Código. "Como provo que funciona" mora no Manual de Testes. Este manual governa a camada de IA especificamente.

Regra de ouro deste acervo: cada regra mora em um lugar só. Quando uma regra depende de outra, ela aponta — nunca copia.

Quanto deste manual é obrigatório depende do porte do projeto — ver Níveis de Exigência. Todo projeto com IA no produto sobe automaticamente para o nível Crítico (ver §1).

1. Princípio e escopo

Este manual governa IA dentro do produto — a inteligência artificial que o usuário experimenta (gera texto, responde perguntas, toma decisões, age). Não governa o agente de IA que programa.

Por que sobe para o nível Crítico automaticamente: todo produto com IA tem, no mínimo, dois dos três elementos que definem o nível Crítico — a IA decide algo que afeta o usuário, e frequentemente também guarda dado pessoal ou separa clientes. Além disso, IA introduz riscos que não existem em código tradicional: saída imprevisível, custo proporcional ao uso, e uma superfície de ataque nova (manipulação da instrução). O nível mais alto é o piso, não a exceção.

Relação com os outros manuais:

A camada de IA é código — segue o Manual de Código em tudo (camadas, separação, qualidade, segurança).
A avaliação da saída de IA é teste — segue o Manual de Testes em tudo (catraca, processo de entrega, trava de subida).
A experiência de IA na tela é design — segue o Manual de Design em tudo (estados de carregamento, mensagens de erro, voz e tom).
Este manual acrescenta o que é específico de IA: a instrução, o modelo, a avaliação, a resiliência e a segurança de IA.

2. Quando usar qual abordagem

Antes de construir, escolher a abordagem certa. São três — com custo, vantagem e limite diferentes:

Abordagem	O que é	Quando usar	Limitação principal
Instrução	Guiar o modelo com um texto que descreve o papel, o contexto e o que deve responder	A grande maioria dos casos: quando o modelo já sabe o suficiente e precisa só de direção	Não funciona para dado muito específico ou muito atualizado que o modelo não conhece
Busca em base de conhecimento	Antes de responder, buscar os trechos relevantes do acervo do produto e passá-los ao modelo junto com a pergunta	Quando o produto tem conhecimento próprio (documentos, regras, histórico) que o modelo não tem	Qualidade depende da qualidade da busca — o modelo só é tão bom quanto o que encontrou
Ajuste fino do modelo	Treinar o modelo com exemplos do domínio para que ele aprenda o estilo, o vocabulário e os padrões do produto	Quando instrução + busca não bastam, o produto tem tom muito específico e há volume suficiente de exemplos de qualidade	Caro, demora, exige conjunto de exemplos curado, e precisa ser refeito a cada versão nova do modelo base

Régua de decisão (nesta ordem):

Instrução resolve? → usar instrução.
O modelo precisa de dado que não tem? → acrescentar busca em base de conhecimento.
Instrução + busca ainda não bastam E há exemplos suficientes E o custo é justificado? → considerar ajuste fino.

Na dúvida, instrução primeiro. É o mais barato, o mais rápido de ajustar e o mais fácil de versionar.

3. Camada de IA isolada

A IA fica numa camada separada com contrato claro — igual ao padrão repositório do banco. O código de regra de negócio nunca chama o fornecedor de IA diretamente — chama a abstração da camada de IA.

Por que: trocar de fornecedor, mudar de modelo, ou adicionar cache não deve exigir tocar na regra de negócio. A abstração protege o resto do código dessa volatilidade.

Estrutura da camada (dentro da pasta de IA do projeto):

providers/ — os adaptadores concretos de cada fornecedor
agents/ — um arquivo por agente, com papel, instrução versionada e capacidades
prompts/ — as instruções versionadas (<agente>/v1.ts, <agente>/v2.ts, …)
evals/ — os conjuntos de avaliação por agente
tools/ — as capacidades que os agentes podem chamar

Exemplo concreto — ponto único de entrada: ver receita R3 no anexo de receitas do acervo.

Escolha de modelo por tarefa:

Leve — classificação, extração de dado estruturado, verificação de formato
Médio — geração de texto, resumo, resposta a perguntas com contexto
Forte — raciocínio complexo, análise de múltiplos documentos, decisão com trade-offs

Versão do modelo sempre fixada. Nunca usar "versão mais recente automática" — o fornecedor pode lançar versão nova que muda o comportamento silenciosamente. A versão do modelo é declarada junto com a instrução. Migrar para versão nova exige avaliação verde primeiro (ver §9).

4. Instrução como artefato

A instrução que vai para o modelo não é texto solto no meio do código. É um artefato versionado — arquivo próprio, com número de versão e histórico de mudança.

Por que: instrução mudada sem rastrear é regressão silenciosa que nenhum teste de código pega. O comportamento do produto muda, mas nenhum log diz o quê ou quando.

Estrutura obrigatória de uma instrução:

Papel — quem o modelo é neste contexto
Contexto — o que o modelo precisa saber para responder bem
Formato de saída — exatamente o que deve devolver (texto livre, formato estruturado com schema definido, lista numerada)
Exemplos — pelo menos um par de entrada/saída esperada nos casos onde o comportamento é sutil
Restrições — o que o modelo nunca deve fazer neste agente

Regras:

Proibido instrução solta no código de aplicação — o vigia barra (ver §14).
Todo arquivo de instrução tem um arquivo de histórico de mudanças — obrigatório antes de mesclar qualquer alteração.
Instrução nova ou modificada exige avaliação verde antes de ir para produção (ver §9).

5. Gerenciamento de contexto

O modelo trabalha dentro de um espaço de contexto — tudo que entra numa chamada (instrução + histórico + dado buscado + pergunta do usuário). Esse espaço tem limite; o que ultrapassa o limite é cortado ou causa erro.

Dois tipos de memória:

Memória de sessão (curto prazo): o histórico da conversa atual. Dura enquanto a sessão existe. Crescer indefinidamente enche o espaço de contexto — definir limite de turnos que entram no histórico.
Memória persistente (longo prazo): dado que sobrevive entre sessões — preferências, histórico resumido, perfil do usuário. Guardado no banco; buscado e injetado no contexto quando relevante.

Como estruturar o que entra no contexto (a ordem importa — o modelo dá mais peso ao início e ao fim):

Instrução do sistema (fixa, sempre primeiro)
Memória persistente relevante (buscada)
Dado da busca em base de conhecimento (buscado)
Histórico recente da conversa (janela deslizante, não tudo)
Pergunta atual do usuário (sempre por último)

Quando o contexto transborda: comprimir o histórico antigo em resumo, buscar só os trechos mais relevantes da base de conhecimento, e sinalizar ao usuário quando a conversa ficou longa demais para ser mantida na íntegra.

6. Saída estruturada e resposta progressiva

Saída estruturada: quando o sistema precisa processar a resposta do modelo (não só mostrar ao usuário), pedir saída em formato definido com schema em vez de texto livre.

Validar a saída contra o schema antes de usar — o modelo pode errar o formato.
Configurar re-tentativa automática (até 3 tentativas) quando o formato é inválido, incluindo a mensagem de erro na re-tentativa para que o modelo corrija.
Se após as tentativas o formato ainda for inválido: registrar como falha e acionar o caminho de degradação (ver §10).

Resposta progressiva: para respostas longas, mostrar ao usuário enquanto o modelo ainda está gerando — a experiência é muito melhor do que esperar o texto inteiro.

Usar em: geração de texto longo, resumos, análises, qualquer resposta que demore mais de 2 segundos.
Tratar erros no meio da geração: o usuário deve ver uma mensagem clara, não a resposta cortada no meio.
O estado de "gerando" é comunicado visualmente — ver Manual de Design (estados de carregamento e esqueletos).

7. Agentes e capacidades

O que é um agente no contexto LZR: uma unidade com papel fixo, instrução versionada, memória própria e um conjunto declarado de capacidades. Cada agente faz uma coisa — agente genérico que faz tudo é antipadrão.

O que são capacidades: ações que o agente pode tomar além de responder texto — buscar dado, criar registro, enviar mensagem, chamar outro sistema. Cada capacidade é declarada explicitamente; o agente só pode usar o que está declarado.

Aprovação humana antes de ação irreversível: quando um agente pode tomar uma ação que não dá para desfazer (apagar, enviar, publicar, cobrar), a ação não acontece automaticamente — o sistema pausa, mostra ao usuário o que vai fazer e aguarda confirmação explícita. Sem exceção.

Exemplo concreto — modo ensaio + carimbo de autor + trava anti-duplicação: ver receita R12 no anexo de receitas do acervo.

Orquestração de múltiplos agentes:

Cada agente recebe só o contexto que precisa — não todo o histórico de tudo.
A falha de um agente tem tratamento explícito — não para o fluxo todo sem aviso.
O resultado intermediário é validado antes de passar para o próximo agente.
Fluxos com mais de 3 agentes em cadeia precisam de aprovação humana nos pontos de risco.

8. Busca em base de conhecimento

Usar quando o produto tem conhecimento próprio (documentos, regras, histórico de conversas, dados do domínio) que o modelo não conhece e que não cabe inteiro no contexto.

O que guardar: trechos com granularidade suficiente para ser útil isolado. Um trecho muito longo dilui a relevância; muito curto perde o contexto. O alvo é o parágrafo ou seção — não o documento inteiro nem a frase solta.

Como medir a qualidade da busca:

Precisão: dos trechos buscados, quantos eram realmente relevantes para a pergunta?
Cobertura: das perguntas feitas, em quantas o trecho certo estava nos resultados?

Esses dois números entram nas avaliações do agente (ver §9) — busca ruim é causa frequente de resposta ruim.

9. Avaliação da saída

O coração do manual. Sem avaliação sistemática não há engenharia de IA — há tentativa e erro em produção. É o que separa IA profissional de IA amadora.

O que é uma avaliação: um conjunto de casos onde cada caso tem (1) uma entrada, (2) um resultado esperado e (3) um juiz que mede se o resultado real chegou perto do esperado. O conjunto cresce com o tempo — cada problema encontrado em produção vira um caso novo.

Três tipos de juiz:

Tipo	Como funciona	Quando usar
Determinístico	Verifica se a saída tem um campo, um formato ou um valor esperado	Saída estruturada, verificações de formato, campos obrigatórios
Heurístico	Mede características sem ler o conteúdo (comprimento, presença de termos, ausência de palavras proibidas)	Checagens rápidas que não precisam de compreensão do significado
Modelo avaliando modelo	Um modelo separado julga se a resposta foi boa, com critérios explícitos	Qualidade de resposta, tom, correção — o que os outros dois não alcançam

A catraca das avaliações: igual à catraca de testes — o placar só sobe, nunca desce. Mudança de instrução ou de modelo que baixa o placar não vai para produção.

Quando rodar:

Antes de mesclar qualquer mudança de instrução ou de versão de modelo.
Automaticamente no processo de entrega, antes de publicar em qualquer ambiente.
Após migrar para versão nova de modelo — comparando placar antigo vs. novo.

Testes adversariais: além das avaliações normais, um conjunto separado tenta ativamente fazer o sistema agir de forma não autorizada:

Tentativas de redirecionar o agente fora do escopo
Entradas extremas (texto muito longo, caracteres especiais, idioma diferente)
Perguntas fora do escopo (o agente deve recusar com elegância, não inventar)
Cenários de fronteira do domínio

10. Resiliência

IA introduz uma dependência externa nova: o fornecedor pode ficar indisponível, o modelo pode falhar, a chamada pode demorar demais. O produto precisa se comportar bem em todos esses casos.

Limite de tentativas e tempo máximo: toda chamada ao modelo tem (1) tempo máximo de espera definido e (2) número máximo de re-tentativas com espera crescente entre elas. Se todas as tentativas falharem, acionar o caminho de degradação.
Alternativa de fornecedor: em serviços críticos, configurar um modelo reserva de um fornecedor diferente. Se o fornecedor principal falhar, a chamada vai para o reserva — o usuário não vê o erro.
Degradação sem IA: toda funcionalidade que depende de IA tem um modo reduzido definido — o que acontece quando a IA não está disponível: mostrar mensagem honesta ao usuário, oferecer alternativa manual quando existir, enfileirar para processar depois quando fizer sentido, nunca deixar o produto travar ou mostrar erro técnico ao usuário.

IA não pode ser ponto único de falha. Um produto que para completamente quando o modelo falha tem problema de arquitetura — não de infraestrutura.

11. Observabilidade e custo

IA é a única parte do sistema onde o custo pode explodir em minutos sem aviso — um laço, um volume inesperado de uso ou um modelo mais caro ativado por engano geram conta imprevista. Monitorar é obrigatório.

O que medir por chamada:

Tempo de resposta (do envio ao recebimento completo)
Custo (volume de texto enviado + recebido, multiplicado pela tarifa do modelo)
Taxa de reaproveitamento de cache de instrução
Resultado: sucesso, falha de formato, falha do fornecedor, tempo esgotado

Alertas obrigatórios:

Custo total do produto por hora ultrapassa o limite definido
Custo por operação específica fica 3× acima da média histórica
Taxa de falha do modelo ultrapassa 5% em qualquer janela de 5 minutos

Cota de custo por cliente: em produto multi-cliente, limitar quanto cada cliente pode consumir de IA por período. Verificar e debitar antes de cada chamada — se não tem cota, a chamada não acontece. Evita que um cliente de uso intenso custe pelos outros.

Exemplo concreto — teto em três degraus (aviso / segura o lote / corta): ver receita R11 no anexo de receitas do acervo.

Cache de instrução: quando a instrução é longa e estável, o fornecedor reaproveita o processamento entre chamadas — reduz custo e tempo de resposta. Estruturar a instrução para maximizar o reaproveitamento: parte estável primeiro, parte variável (contexto do usuário) por último.

12. Segurança de IA

IA introduz uma superfície de ataque que não existe em código tradicional: a instrução é manipulável pelo usuário.

A ameaça principal — manipulação da instrução: o usuário insere texto na entrada que redireciona o modelo para agir fora do escopo definido. O modelo pode obedecer — ele não tem como saber que a instrução veio do atacante, não do sistema.

O "trifecta letal": qualquer sistema que reúne os três elementos abaixo ao mesmo tempo precisa de proteção explícita e revisão de segurança dedicada:

Acesso a dado sensível (dado de cliente, dado financeiro, dado pessoal)
Capacidade de agir (criar, alterar, enviar, cobrar)
Confiança no texto que o usuário manda

Como proteger:

Separar instrução de sistema de entrada do usuário com delimitadores claros e consistentes.
Nunca concatenar entrada do usuário diretamente dentro da instrução.
Validar e sanitizar entrada antes de enviar ao modelo.
O modelo não decide sozinho quem pode ver o quê — a autorização é verificada pelo código, não pela instrução.
Nunca confiar que o modelo vai rejeitar instruções maliciosas por conta própria.

O que nunca fazer:

Chave de acesso ao fornecedor de IA no código.
Modelo com acesso a sistema de escrita sem confirmação humana (ver §7).
Saída do modelo indo direto para o banco sem validação.
Instrução que contém dado pessoal ou segredo do sistema.

13. Privacidade, conformidade e auditoria

Dado pessoal não vai para o modelo sem consentimento e contrato. O fornecedor de IA processa o texto que recebe — se esse texto contém nome, dado de saúde, ou qualquer informação pessoal identificável, é preciso:

Consentimento do usuário para que o dado seja processado por terceiro.
Contrato de processamento de dado com o fornecedor (verificar se está assinado antes de ativar a funcionalidade).
Confirmar se o fornecedor usa as chamadas para treinar o modelo base — e desligar se necessário.

Registro de decisões de IA: em produto de nível Crítico, toda decisão que a IA tomou é registrada de forma que possa ser consultada depois:

O que entrou (entrada do usuário, versão da instrução, modelo usado)
O que saiu (resposta completa do modelo)
Quando aconteceu e quem era o usuário

14. Vigias automáticos

Rodam no projeto, antes de qualquer mudança subir. Seguem o mesmo princípio dos vigias de código — todo vigia fala, nunca só "falhou".

Vigia	O que verifica	Tipo
Instrução fora da camada de IA	Barra texto de instrução detectado fora da pasta `prompts/` ou `agents/`	Dura
Agente sem avaliação	Barra agente sem arquivo de avaliação correspondente em `evals/`	Dura
Instrução sem histórico de mudança	Barra mudança em arquivo de instrução sem histórico atualizado	Dura
Versão de modelo não fixada	Barra referência a "última versão" em vez de versão específica	Dura
Chave de fornecedor no código	Barra padrão de chave de acesso detectado fora de arquivo de ambiente	Dura

O que é subjetivo e não vira trava automática:

Qualidade real da avaliação (o vigia verifica que existe; não verifica se os casos são bons o suficiente).
Segurança semântica da instrução (o vigia verifica que está na camada certa; não verifica se protege contra manipulação).
Adequação do modelo escolhido para a tarefa.

Fronteiras deste manual: como construo o código da camada de IA → Manual de Código. Como provo que funciona → Manual de Testes. Como a experiência de IA aparece na tela → Manual de Design.