Da ideia à produção
Explore cada etapa →
As contas, num só lugar
As 9 contas desta página. Clique em qualquer uma para pular para a etapa que a explica.
Panorama
Da ideia à produção
Explore cada etapa →
As contas, num só lugar
As 9 contas desta página. Clique em qualquer uma para pular para a etapa que a explica.
SDD (Spec-Driven Development) é escrever a especificação antes do código e tratar a spec, não o prompt, como a fonte da verdade. Com agente de código isso deixou de ser burocracia: o modelo não pergunta, ele completa. Cada coisa que a spec não diz vira uma decisão que ele toma sozinho, com cara de certeza. Abaixo, a mesma tarefa com e sem cada seção da spec. As perguntas da direita são as que o agente vai responder por conta própria.
O arquivo que o agente recebe
p é a chance de o agente acertar uma decisão adivinhada; a é quantas decisões ficaram para adivinhar. A conta supõe chutes independentes, o que é otimista: um chute errado no começo (o separador do CSV) costuma arrastar outros.
O ciclo, na prática
Critério no formato EARS (Easy Approach to Requirements Syntax): QUANDO <gatilho>, O SISTEMA DEVE <resposta>, com variantes para estado (ENQUANTO), opcional (ONDE) e erro (SE ... ENTÃO). A forma fixa elimina o "deve ser rápido" e força algo que um teste consegue conferir. É o formato que o Kiro, da AWS, usa no requirements.md.
Spec viva: o GitHub Spec Kit separa o trabalho em comandos (especificar, planejar, quebrar em tarefas, implementar) e guarda tudo em arquivos versionados junto do código. Quando o comportamento muda, muda a spec primeiro e o código depois; o diff da spec vira a revisão de produto.
Constituição do projeto: regras que valem para toda tarefa (stack, padrões, o que nunca fazer) ficam num arquivo lido no começo de toda sessão. É a mesma ideia da memória do harness, na etapa 6: o que se repete não deveria ser redigitado no prompt.
Quando não vale: protótipo de uma tarde, correção de uma linha, exploração em que você ainda não sabe o que quer. Aí a spec é o próprio experimento.
A API não lembra de nada entre chamadas: tudo que o modelo sabe numa resposta foi enviado naquela chamada. Engenharia de contexto é decidir o que entra nessa janela, em que ordem e em que tamanho. Prompt é só uma das fatias. As outras (ferramentas, histórico, documentos) costumam ser maiores, e são as que fogem do controle.
A janela, fatia por fatia
System, ferramentas, histórico, documentos e pergunta precisam caber na janela J menos a reserva R da resposta, porque a saída divide a mesma janela. Caber é a condição mínima. A boa prática é ficar bem abaixo do teto: atenção espalhada por mais tokens acha pior o que importa.
Boas práticas
Compactação: quando o histórico passa de um limite, o harness pede ao modelo um resumo do que importa (decisões, arquivos, pendências) e troca os turnos velhos por ele. Perde detalhe, ganha espaço. Resultados de ferramenta antigos são os primeiros a sair: o modelo já agiu sobre eles.
Subagentes: uma busca que lê 40 arquivos roda num contexto separado e devolve 20 linhas. A janela principal recebe a conclusão, não a pilha. O preço é que o agente principal não vê o que o subagente descartou.
Memória fora da janela: anotações em arquivo (um NOTES.md, uma lista de tarefas) que o agente lê e escreve. A tarefa longa sobrevive à compactação porque o estado está no disco, não no contexto. A página RLM leva isso ao extremo: o dado inteiro fica fora e o modelo consulta por código.
Contexto longo não é RAG grátis: uma janela de 1M tokens cabe um livro, mas cada chamada paga o livro inteiro e a qualidade cai com a distância. Para base que muda e cresce, buscar continua mais barato e mais preciso.
RAG (Retrieval-Augmented Generation) tem duas metades: buscar os trechos que respondem à pergunta e gerar a resposta com eles colados no prompt. A segunda metade é o modelo; a primeira é engenharia de busca, e é onde a maioria dos RAGs falha. Abaixo, uma central de ajuda de loja com seis textos, picada em pedaços e buscada de verdade, de três jeitos.
A pergunta
O ranking dos pedaços
A busca por palavra que move a maioria dos buscadores há décadas. Palavra rara pesa mais (idf), repetir a palavra ajuda até saturar (k₁), e pedaço longo é penalizado (b). Ela acerta código de produto, nome próprio e termo exato, onde o vetor tropeça; erra sinônimo e variação de grafia, onde o vetor brilha.
A busca híbrida junta as duas listas sem comparar notas de escalas diferentes: só a posição importa. Teste nas três buscas: em "Entregas no domingo?" o BM25 erra (o texto diz "Domingos", outra palavra para ele) e os trigramas acertam; em "Qual o prazo do Pix?" é o contrário. A híbrida acerta as duas. E "Dá pra parcelar?" nenhuma acha, porque o texto diz "10 vezes": sinônimo é trabalho de embedding.
Boas práticas
Reranking: recupere 20 a 50 candidatos barato (híbrida) e reordene com um modelo de cross-encoder, que lê pergunta e pedaço juntos e dá uma nota mais fina. Mais lento por par, por isso só nos candidatos. Fica com os 3 a 5 melhores.
Contextual retrieval: antes de indexar, um modelo escreve uma frase de contexto para cada pedaço ("Este trecho é da política de reembolso, sobre prazos no cartão") e ela é indexada junto. A Anthropic mediu 49% menos falhas de recuperação com isso mais BM25, e 67% somando reranking. Com cache de prompt, gerar o contexto do documento inteiro sai barato.
Reescrever a pergunta: "e no Pix?" sozinho não acha nada. Reescreva com o histórico ("prazo de reembolso no Pix") antes de buscar, ou gere uma resposta hipotética e busque por ela (HyDE).
Quando o vetor não basta: pergunta que exige ligar fatos de vários documentos ("quais fornecedores do produto X também atrasaram em março?") pede grafo. A página Grafos mostra o híbrido. E RAG agêntico é dar a busca como ferramenta e deixar o modelo buscar de novo quando o primeiro resultado não basta.
Fine-tuning é continuar o treino de um modelo pronto com exemplos seus. Ele muda como o modelo responde (formato, tom, uma tarefa estreita) muito melhor do que muda o que ele sabe. A ordem que funciona: prompt primeiro, RAG quando falta conhecimento, fine-tuning quando o comportamento não sai com prompt e você tem dados para ensinar. Responda as perguntas abaixo.
Pontos de cada caminho (regra escrita à mão)
Se for treinar: quanta memória
O treino cheio guarda, por parâmetro, o peso em bf16 (2 bytes), o gradiente (2), uma cópia mestre em fp32 (4) e os dois momentos do Adam em fp32 (8). O LoRA congela o modelo: só os pesos em bf16 ficam na GPU, mais adaptadores que somam menos de 1%. O QLoRA guarda a base em 4 bits.
QLoRA (Dettmers e colegas, 2023): base quantizada em 4 bits no formato NF4, adaptadores LoRA em bf16 por cima e otimizador paginado para picos de memória. Ajustou um modelo de 65 bilhões numa única GPU de 48 GB, com qualidade perto do ajuste em 16 bits.
SFT e DPO: o ajuste supervisionado (SFT) ensina com pares de pergunta e resposta ideal. O DPO (Direct Preference Optimization, 2023) ensina com pares de resposta preferida e rejeitada, sem treinar um modelo de recompensa à parte. Serve para preferência que é fácil de julgar e difícil de escrever: "esta resposta é melhor que aquela".
Destilação: um modelo grande gera milhares de respostas boas e um modelo pequeno é ajustado nelas. É o caminho para trocar uma chamada cara por uma barata numa tarefa estreita, e é onde fine-tuning mais paga a conta.
Esquecimento catastrófico: ajustar forte numa tarefa piora outras. Taxa de aprendizado baixa, poucas épocas, LoRA (que não mexe nos pesos originais) e misturar exemplos gerais no conjunto seguram o estrago. Meça as duas coisas: a tarefa nova e um conjunto do que já funcionava. A página Fine-tuning faz a conta do LoRA camada a camada.
Uma eval é um conjunto de casos com um jeito automático de conferir a resposta: um teste que passa ou falha, uma rubrica, uma resposta esperada. É o que transforma "mudei o prompt e parece melhor" em número. E número de amostra pequena precisa de intervalo: abaixo, a versão A acerta 72% e a B, 80%, em 50 casos. B é melhor?
Onde o acerto verdadeiro provavelmente está (95%)
O intervalo de Wilson dá a faixa do acerto verdadeiro a partir do medido. O veredito acima vem de um teste de duas proporções, e o tamanho de amostra, da conta de poder estatístico (95% de confiança, 80% de poder). Com 50 casos, 8 pontos de diferença ainda é ruído.
Acertar uma vez ou acertar sempre
Três jeitos de conferir, do mais barato ao mais caro
Eval-driven development: antes de mexer no prompt, escreva os casos que hoje falham. A mudança só entra se esses passarem e os antigos não piorarem. A eval roda na CI como um teste qualquer, com o resultado guardado por versão de prompt e de modelo.
pass@k sem viés: a fórmula 1 − (1−p)^k supõe tentativas independentes com p conhecido. Na prática, gere n ≥ k amostras por problema, conte c corretas e use 1 − C(n−c, k) / C(n, k), o estimador do artigo do Codex (Chen e colegas, 2021).
Eval de agente: confira o estado final (o banco ficou certo? o teste passa?) e não o caminho, porque há muitos caminhos certos. O τ-bench mediu pass^k em atendimento simulado e mostrou modelos fortes caindo bem abaixo da metade quando precisam acertar a mesma tarefa 8 vezes seguidas.
Contaminação e vazamento: casos públicos podem estar no treino do modelo. Mantenha um conjunto próprio, privado, tirado do seu tráfego real (etapa 9), e renove de tempos em tempos.
O harness é tudo que roda em volta do modelo num agente: o laço que chama a API, executa as ferramentas e devolve o resultado, mais as regras de quando parar, o que pode ser feito sem perguntar, como o contexto é mantido e como o trabalho é conferido. Dois agentes com o mesmo modelo e harness diferentes têm resultados muito diferentes. Ligue e desligue as peças.
O que ainda pode dar errado
Por que a verificação é a peça que mais pesa
Hooks: código seu que roda em eventos do laço (antes de uma ferramenta, depois de uma edição, no fim da resposta). Um hook pode bloquear um comando perigoso, rodar o formatador ou devolver o erro do compilador ao modelo. A regra fica determinística: não depende de o modelo lembrar.
Permissões em camadas: ler é livre, editar dentro do projeto é livre, rodar comando de uma lista é livre, o resto pergunta. Ações irreversíveis (deploy, e-mail, pagamento, apagar) sempre perguntam. O modo "faça tudo sem perguntar" só dentro de sandbox descartável.
Orquestração: um agente coordenador quebra a tarefa e distribui para subagentes com contexto e ferramentas próprios, em paralelo quando as partes não dependem umas das outras. Ganha velocidade e contexto limpo; paga em tokens (cada subagente lê o que precisa) e em coordenação.
Workflow antes de agente: se os passos são sempre os mesmos, um fluxo fixo com chamadas de modelo em pontos definidos é mais barato, mais rápido e mais fácil de testar. Agente é para quando o caminho depende do que aparece no meio. A página Um agente de verdade monta o laço com LangGraph.
O MCP (Model Context Protocol) é um protocolo aberto, criado pela Anthropic em 2024, para um app com IA (o host) se ligar a servidores que oferecem ferramentas, dados e prompts. Antes dele, cada integração era escrita de novo para cada app; com ele, um servidor de GitHub escrito uma vez funciona em qualquer cliente que fale o protocolo. Por baixo, são mensagens JSON-RPC 2.0, por stdio (processo local) ou HTTP (servidor remoto). Avance as mensagens.
O preço de plugar
O risco de plugar
A descrição de cada ferramenta vai direto para o prompt do modelo, e quem escreve a descrição é o autor do servidor. Um servidor malicioso, ou comprometido depois de instalado, pode esconder instruções ali. Isso se chama envenenamento de ferramenta; quando a descrição muda depois que você aprovou, é o rug pull.
O usuário vê "listar_issues" na tela de aprovação. O modelo lê o texto inteiro. Avance de novo as mensagens acima: o tools/list agora traz esta descrição.
Servidor remoto e autorização: por HTTP, o servidor MCP é um servidor de recursos OAuth 2.1. O cliente obtém um token com PKCE, preso àquele servidor (resource indicators), e o servidor não deve repassar o token do usuário para APIs de terceiros. Servidor local por stdio herda as permissões do seu usuário no sistema: trate como instalar um programa.
Além de tools: o servidor também oferece resources (dados para ler, como arquivos ou linhas de tabela) e prompts (modelos prontos que o usuário escolhe). O cliente pode oferecer roots (que pastas o servidor enxerga), sampling (o servidor pede uma geração ao modelo do host) e elicitation (o servidor pede um dado ao usuário no meio da tarefa).
Defesas: instale só servidores que você confia e fixe a versão; mostre a descrição completa na aprovação e peça aprovação de novo se ela mudar (guarde um hash); dê ao servidor o menor escopo de token possível; não ligue no mesmo agente um servidor que lê dado privado e outro que manda coisas para fora sem revisão (é a tríade da etapa 8).
Ferramenta sob demanda: com dezenas de servidores, as definições sozinhas comem a janela e o modelo escolhe pior. A saída é oferecer uma ferramenta de busca de ferramentas e carregar a definição completa só quando ela for usada.
Modelo de linguagem não separa instrução de dado: tudo é texto na mesma janela. Por isso injeção de prompt não tem conserto dentro do modelo, só mitigação. A boa notícia é que o estrago precisa de capacidades que o seu código dá ao agente. Simon Willison chamou de tríade letal a combinação que permite vazar dados: acesso a dado privado, exposição a conteúdo não confiável e um canal para mandar coisas para fora.
As capacidades do agente
As defesas no seu código
Seis ataques contra esta configuração
OWASP Top 10 para aplicações com LLM (2025)
Padrão dual LLM: um modelo privilegiado planeja e chama ferramentas, mas nunca lê conteúdo não confiável; um modelo em quarentena lê o conteúdo e devolve só valores em variáveis ($resumo1), que o privilegiado repassa sem ler. A injeção fica presa no modelo que não pode agir.
CaMeL (Google DeepMind, 2025) leva a ideia adiante: o modelo privilegiado escreve um programa a partir só do pedido do usuário; dados não confiáveis entram como valores com etiqueta de origem, e uma política checa cada chamada de ferramenta ("este e-mail pode ir para um endereço que veio de uma página web?"). Segurança vem do fluxo de dados, não de o modelo resistir.
Permissão no dado, não no prompt: no RAG, filtre os documentos pela permissão do usuário na busca, antes de chegar ao modelo. "Não mostre documentos de outros clientes" escrito no prompt não é controle de acesso.
Saída é entrada de outro sistema: escape a resposta antes de virar HTML, use consultas parametrizadas se ela virar SQL, nunca passe direto para um shell. Formatos de modelo também: prefira safetensors a pickle, que executa código ao carregar.
Um sistema com IA erra de um jeito que log comum não explica: a resposta saiu errada porque a busca trouxe o trecho errado, ou porque o histórico estourou, ou porque o modelo pediu a ferramenta com o argumento trocado. Observabilidade é guardar, por requisição, o que o modelo viu, o que ele pediu, quanto custou e quanto demorou. Comece pela conta do mês.
Preços de exemplo, na ordem de grandeza de um modelo intermediário. Confira a tabela do seu provedor.
por requisição
por dia
por mês (30 dias)
O trace de uma requisição
Cada barra é um span: um pedaço do trabalho com início, fim e atributos. Clique para ver o que cada um guarda. Os nomes dos atributos seguem as convenções do OpenTelemetry para IA generativa.
O que medir desde o dia 1
Fechar o ciclo: trace com nota baixa vira caso de eval (etapa 5), a eval barra a próxima versão que piorar, e a spec (etapa 1) ganha o caso de borda que ninguém previu. É o mesmo laço da figura do panorama.
Privacidade no trace: prompt e resposta carregam dado pessoal. Mascare antes de gravar, defina retenção, restrinja quem lê. Amostre: 100% dos erros e uma fração do tráfego normal costuma bastar.
Roteamento: um modelo pequeno e barato atende o caso fácil e escala para o grande só quando a confiança é baixa. A página System One faz a conta dessa cascata. Somado ao cache e a respostas curtas, costuma cortar a fatura mais que trocar de fornecedor.
Lote assíncrono: o que não precisa de resposta na hora (classificar o histórico, gerar contexto para o RAG, rodar a eval) vai por API de lote, que os provedores costumam cobrar pela metade.
O caminho inteiro
Continue na série