Um sistema de IA bem-sucedido tem muito pouca IA no caminho crítico.

Da abstração ao código

Os princípios, em código real

Não é teoria: cada princípio vira poucas linhas de engenharia disciplinada. Python puro, contratos estritos e o LLM contido a um único passo.

from pydantic import BaseModel, Field

class Inference(BaseModel):
    model_config = {"extra": "forbid"}         # rejeita campo inesperado do LLM
    intent: str
    confidence: float = Field(ge=0.0, le=1.0)  # limite no schema, nao no if

def run_pipeline(item, llm):
    # Serve a qualquer dominio: leads B2B, tickets de suporte,
    # pedidos de e-commerce, laudos medicos -- a estrutura e a mesma.
    signals = collect_signals(item)            # M1: deterministico (APIs, banco, sem IA)
    if signals.missing:                        # Open-World: ausencia = incerteza
        return Inference(intent="desconhecido", confidence=0.0)
    raw = llm.extract(signals.snippet)         # M2: LLM so no residuo interpretativo
    return Inference.model_validate(raw)       # valida a saida (input nao confiavel)

class TokenLedger:
    def __init__(self, daily_cap: int):
        self.cap = daily_cap
        self.spent = 0

    def try_spend(self, n: int) -> bool:
        if self.spent + n > self.cap:          # teto do dia atingido
            return False                       # falhar e parar: sem fatura surpresa
        self.spent += n
        return True

ledger = TokenLedger(daily_cap=1000)
for item in fila:
    if not ledger.try_spend(cost(item)):
        mark_pending(item)                     # retoma na proxima onda
        break                                  # para limpo, em ponto seguro

def explain(score):
    # nunca exponha o numero: traduza em "por que agora" + "o que falta"
    return {
        "why_now": [d.text for d in score.positive_signals],
        "gaps": score.missing_signals,         # honestidade Open-World
        "sources": [d.url for d in score.references],
    }

Trilha guiada

Aprenda por descoberta

Dez capítulos, do caos dos prompts ao projeto completo. Abra cada um para ver o objetivo e o que você sai sabendo.

1. 01 Da magia à engenharia Iniciante · 6 min

   Ninguém constrói um sistema bancário deixando o banco de dados "decidir livremente" o que fazer com cada transação. O banco é poderoso, mas opera dentro de transações, constraints e contratos rígidos — é poderoso porque é contido. Um LLM merece o mesmo respeito arquitetural.

   O problema: a forma mais sedutora de construir com IA é encadear prompts e dar autonomia total ao modelo. Funciona numa demo; em produção, gera defeitos que o software clássico raramente enfrenta — loops infinitos (um agente devolve a tarefa ao outro e cada volta custa dinheiro), custo imprevisível, alucinações que se propagam quando a saída inventada de um vira entrada do outro, e irreprodutibilidade (a mesma entrada produz saídas diferentes, impossível de depurar).

   A solução é cultural antes de técnica: parar de tratar o modelo como mágica e tratá-lo como engenharia. Aplica-se ao componente probabilístico tudo o que já sabemos sobre software confiável — contratos de interface, testes determinísticos, controle de orçamento, isolamento de responsabilidades.

   Na prática, isso significa que a capacidade vem do modelo, mas a confiança vem da engenharia ao redor dele.

   Princípio 1 →

2. 02 Orquestração determinística Iniciante · 8 min

   Pense num fluxograma fixo de uma fábrica: cada estação faz uma coisa específica e passa o resultado adiante. Compare com uma sala onde várias pessoas conversam tentando decidir o que fazer a seguir. O primeiro é um DAG — um grafo de etapas fixas; o segundo é uma conversa aberta entre modelos.

   O problema: dar ao LLM autoridade sobre o fluxo de controle ("agentes decidem tudo de ponta a ponta") é flexível e impressionante — e impossível de garantir. Não dá para prometer prazo, estimar custo ou passar por auditoria.

   A solução é separar duas camadas que costumam ser confundidas. A camada de orquestração/I-O pode ser assíncrona e tolerante a falhas — é a borda do sistema. A camada de decisão/cálculo deve ser pura e determinística — é onde o resultado é computado, sem aleatoriedade. O modelo é chamado dentro de uma etapa para fazer uma coisa; ele nunca decide qual será a próxima.

   Na prática, isso significa que o LLM responde perguntas — ele não decide quais perguntas fazer a seguir.

   Princípios 1 e 2 →

3. 03 Cérebro × Vitrine Intermediário · 7 min

   É a diferença entre a cozinha de um restaurante e o salão. A cozinha é quente, perigosa e não muda toda semana — é onde o trabalho pesado acontece. O salão é a parte que o cliente vê e que você redecora com frequência. Você não coloca o fogão no meio das mesas, e não dá ao cliente a chave do estoque.

   O problema: sistemas cognitivos têm dois perfis de carga opostos. O "Cérebro" (motor cognitivo) é pesado, assíncrono, sensível (chaves, dados, lógica proprietária) e muda raramente. A "Vitrine" (interface) é leve, síncrona, exposta à internet pública e muda o tempo todo. Atendê-los na mesma aplicação é uma armadilha clássica: uma falha na vitrine exposta compromete o motor, e cada mudança de interface arrisca a lógica.

   A solução é separá-los fisicamente e conectá-los por um contrato estreito — tipicamente uma API com pouquíssimos endpoints —, nunca por um banco de dados compartilhado. O cérebro processa em segundo plano e publica um snapshot pronto; a vitrine apenas lê o resultado e coleta feedback, devolvido de forma controlada.

   Na prática, isso significa que a equipe itera na interface todos os dias sem nunca arriscar o motor sensível.

   Princípio 3 →

4. 04 Determinístico-primeiro Intermediário · 7 min

   Antes de ligar o motor caro, resolva o máximo com o que já está estruturado — como um bom cozinheiro que prepara tudo que dá para preparar antes de acender o fogão. A regra de ouro da confiabilidade é contraintuitiva: use a IA o mínimo possível.

   O problema: cada responsabilidade entregue ao LLM é uma fonte de alucinação e um custo. Mandar o modelo "descobrir" algo que uma consulta a banco, uma regra de negócio ou uma busca exata já responde é desperdiçar dinheiro e introduzir risco onde não precisava existir.

   A solução: mapeie cada campo da tarefa e pergunte — "isso pode vir de uma fonte estruturada, de uma regra ou de uma busca exata?" Se sim, não é trabalho de IA. O que sobra — desambiguar texto livre, inferir intenção, classificar tom — é o resíduo interpretativo. Só ele justifica o custo e o risco de uma chamada de modelo. E esse resíduo encolhe a cada versão, conforme você descobre o que mais pode ser determinístico.

   Na prática, isso significa que menos IA no caminho é, ao mesmo tempo, menos custo e mais confiança.

   Princípio 4 →

5. 05 Contratos rígidos Intermediário · 8 min

   Você nunca confiou cegamente no que o navegador envia para o backend — sempre validou no servidor. Um schema estrito é o mesmo validador de formulário, agora aplicado à saída do LLM: ela é input não confiável por definição, até passar pelo porteiro.

   O problema: se o modelo inventa um atributo, alucina um formato ou devolve score = 1.7 onde o intervalo é 0–1, e isso entra no sistema sem validação, o erro se propaga silenciosamente — e só aparece três etapas depois, irreconhecível.

   A solução é blindar toda fronteira com contratos estritos. Boas práticas concretas: proíba o desconhecido (rejeite qualquer campo fora do esquema em vez de ignorá-lo); coloque os limites no schema, não num if perdido (é o esquema que recusa o 1,7); valide tipos estaticamente quando a linguagem permitir; e degrade item a item — num lote, um item malformado é marcado como incerto, não derruba o lote inteiro. Inclui também sanitizar input adversarial antes do Cérebro.

   Na prática, isso significa que a validação falha imediatamente e de forma barata, em vez de propagar o erro.

   Princípio 5 →

6. 06 Open-World Intermediário · 7 min

   Imagine cadastrar um cliente totalmente novo, sem nenhum histórico no banco. O software clássico opera sob "mundo fechado": o que não está no banco é falso. Sistemas de inteligência precisam do oposto — o Mundo Aberto: a ausência de evidência é incerteza, não negação.

   O problema: "não encontramos sinal de que o cliente está insatisfeito" não é o mesmo que "o cliente está satisfeito" — é "desconhecido". Tratar a lacuna como um "falso" inventa uma conclusão onde não há evidência: a pior categoria de falha, uma decisão de negócio errada tomada com falsa confiança.

   A solução tem duas faces. Primeiro, isole as camadas epistêmicas: evidência observada ≠ inferência gerada ≠ julgamento final, mantendo a rastreabilidade até a fonte — uma inferência tratada como fato vira "evidência" de si mesma e o sistema passa a acreditar nas próprias invenções. Segundo, faça da incerteza um estado de primeira classe: o que não foi observado é informação valiosa ("não foi possível confirmar X"), e falhas de sensor degradam para incerteza, nunca para um valor inventado.

   Na prática, isso significa que ensinar o sistema a dizer "não sei" o torna mais confiável e mais seguro.

   Princípios 6 e 7 →

7. 07 FinOps de IA Avançado · 8 min

   Você já domina pagination e job queues para processar grandes volumes sem derrubar o banco, e cache para não repetir trabalho caro. FinOps de IA é aplicar esses mesmos padrões a um recurso cujo "miss" custa uma chamada de modelo, não um SELECT.

   O problema: tratar limites de token e crédito com try/except em cima do erro de rate limit é frágil e amador. Um fluxo livre transforma o orçamento em variável aleatória — o mesmo pedido pode custar centavos ou dezenas de reais.

   A solução: modele o orçamento como estado de domínio persistente — um ledger que sobrevive entre execuções, sabe quanto já gastou, reseta no período e recusa o gasto ao se aproximar do teto, antes de o provedor recusar por você. Combine com três hábitos: poda precoce (o filtro mais barato primeiro — lixo nunca chega ao LLM); processamento em ondas resumíveis (cada onda salva o progresso e para limpo; a próxima retoma de onde parou); e um corpus acumulativo com chave idempotente — se já foi processado, não processe de novo.

   Na prática, isso significa que o sistema fica mais barato por item conforme cresce.

   Princípio 8 →

8. 08 BDD para IA Avançado · 8 min

   Como testar um sistema cujo componente central é estocástico — que pode responder diferente a cada execução? A resposta é isolar a estocasticidade nos testes: você não testa se o modelo é "inteligente"; testa se o sistema ao redor dele permanece correto quando o modelo, a rede ou os dados falham.

   O problema: sem critério objetivo de "pronto", "funcionou" é uma percepção, não uma verificação — e alucinações elegantes passam despercebidas. Pior ainda ao delegar a agentes de código autônomos, que não têm bom senso para preencher lacunas: ambiguidade entregue a um agente vira alucinação de escopo.

   A solução: escreva cenários em Gherkin (Dado/Quando/Então) antes do código, com chamadas externas substituídas por fixtures gravadas — teste determinístico e de custo zero de API. Todo cenário cobre três eixos: caminho feliz, modo degradado (uma API cai, estoura limite ou dá timeout — o sistema degrada graciosamente) e open-world (um sinal esperado está ausente). Reforce com portões: a DoR impede uma tarefa de entrar com decisões em aberto; a DoD é fail-closed — se não foi possível concluir, registra-se o bloqueio e para-se num ponto seguro.

   Na prática, isso significa que um "BLOQUEADO" honesto é sucesso do processo; um "concluído" falso é dívida que vence com juros.

   Princípio 9 →

9. 09 XAI Intermediário · 6 min

   Ninguém toma uma decisão importante porque "o algoritmo deu 0,674". Compare com: "priorizado porque sinalizou expansão recente e tem histórico de compra no setor; não foi possível confirmar o orçamento". O número é inútil e não inspira confiança; a justificativa, sim.

   O problema: a "caixa preta" é o maior bloqueador de adoção corporativa de IA. Um score opaco gera resistência do usuário, enxurrada de "por que o sistema sugeriu isso?" no suporte e reprovação em auditorias de explicabilidade.

   A solução é trocar o número por uma explicação acionável com três elementos: drivers em linguagem natural (o que pesou a favor e contra), sinais ausentes (a honestidade do Open-World — mostrar a lacuna aumenta a confiança mais do que escondê-la) e proveniência (de qual fonte veio cada sinal, para o usuário verificar). Dois cuidados tornam a XAI confiável: gere a explicação por regras determinísticas sobre o mesmo objeto que gerou a pontuação — nunca com uma segunda chamada de LLM, que racionalizaria; e considere esconder o número e mostrar só o "por que agora" e "o que falta saber".

   Na prática, isso significa que uma resposta explicável e modesta vence uma resposta exata e opaca em adoção.

   Princípio 10 →

10. 10 Projeto completo Síntese · 10 min

    Tudo se junta num caso real: o SocialSelling, um sistema de priorização de leads B2B onde os dez princípios viraram produto. O pipeline é determinístico em cinco módulos — M1 Busca, M2 Extração, M3 Score, M4 Ranking, M5 XAI —, e o LLM atua só em M2 e M5; M3 e M4 são Python puro.

    Como os princípios aparecem: o LLM é componente contido (P1/P2) num fluxo determinístico (P4); o Cérebro local publica snapshots e o portal nunca toca o banco do motor (P3); schemas estritos blindam toda fronteira (P5) e ledgers governam requisições e créditos (P8); a operadora vê "por que agora" e "o que falta", nunca o score (P10). A ausência de dado vira incerteza explícita (P6/P7), e cenários BDD degradados sustentam a governança fail-closed (P9).

    A virada final: quando a IA passa de copilot a desenvolvedora autônoma, a responsabilidade migra para a máquina — e isso exige estrutura. O contexto sai da cabeça e entra no repositório (ADRs, SDDs, DoR/DoD versionados), porque contexto não documentado é contexto que não existe.

    Na prática, isso significa que a disciplina central é distinguir o implementado do especificado — saber quando não construir.

    Governança Agent-Driven →

Verifique seu entendimento

Oito cenários reais — quatro sobre os dez princípios, quatro sobre os cinco pilares. Não decore a regra; escolha o que faria em produção. Cada resposta explica o porquê.

Laboratório

Playground: monte sua arquitetura

Adicione componentes e veja o sistema avaliar a arquitetura por regras determinísticas — apontando riscos e boas práticas.

Consulta rápida

Referência e caso real

Os dez princípios em uma frase, um glossário dos termos-chave e o estudo de caso que originou este conteúdo.

Glossário

Alucinação sintática

Código esteticamente perfeito, porém logicamente errado — aparência de correção sem substância.

Resíduo interpretativo

A fração da tarefa que exige linguagem/inferência e que nenhuma fonte estruturada cobre. Só ele justifica gastar IA.

Open-World

Ausência de evidência é incerteza, não negação. O sistema aprende a dizer "não sei".

Ledger de quota

Orçamento como estado de domínio persistente: sabe quanto gastou, reseta no período e recusa o gasto ao bater o teto.

XAI

Explicação por drivers em linguagem natural + lacunas + proveniência, no lugar do número opaco.

DoR / DoD

Portões de qualidade que fecham a ambiguidade antes (Ready) e validam o resultado depois (Done), com bloqueio honesto.

Espectro de Autonomia

O contínuo entre exploração e missão crítica. A posição correta é função do custo do erro × reversibilidade — uma decisão de design, não um acidente. Pilar 1 →

Vazamento de modo

Código nascido em exploração (descartável) que migra para produção sem nunca atravessar a fronteira de rigor correspondente. O risco operacional mais insidioso.

Regra de transição

A leveza é legítima enquanto o artefato permanece no polo de origem. Quando alguém passa a depender dele como produção, a promoção obriga o upgrade de garantias. Pilar 5 →

ADR

Architecture Decision Record: registro versionado e imutável de uma decisão arquitetural, seu contexto e consequências. Memória que impede reabrir o que já foi fechado — e vira contexto injetável para o agente.

MCP

Model Context Protocol: protocolo aberto cliente-servidor que padroniza a conexão do agente a ferramentas e dados. A fronteira onde se aplica autorização, escopo de permissão e auditoria — acesso enumerado, não ambiente. Pilar 3 →

A2UI (camada)

A fronteira contratual agente↔interface: o Cérebro emite intenção e dados estruturados; a Vitrine decide a renderização. Padrão arquitetural (não especificação canônica) — ver AG-UI e A2A como protocolos reais adjacentes.

Sistema Intencional

Sistema cujo comportamento é governado por intenção arquitetural explícita, não pela saída mais provável do modelo. A garantia mora na arquitetura, que encapsula a probabilidade. Maturidade →

Sandbox (freios)

O espaço delimitado por DoR/DoD/ADR dentro do qual o agente opera em capacidade máxima — porque as bordas são conhecidas. A restrição aumenta a velocidade segura. Pilar 2 →

Estudo de caso: SocialSelling

Seu progresso nesta sessão

Métricas calculadas no seu navegador (localStorage) — nada é enviado a servidor.