Engenharia de agentes de IA
PT-BR

Prefácio

Prefácio

Este livro existe por causa de um momento específico, e suspeito que você já passou por ele. Você entrega a um modelo de linguagem uma tarefa que tomaria meia hora de uma pessoa: descobrir por que o build quebrou, digamos, ou conciliar uma planilha bagunçada com o banco de dados. Em vez de uma resposta, você o vê trabalhar. Ele pesquisa, lê, tenta alguma coisa, esbarra em um erro, se corrige e volta alguns minutos depois, com tudo pronto. A primeira sensação é de encanto. A segunda chega um instante depois e dura mais: Eu não vi todos os passos. Até que ponto posso confiar nisso?

Essa segunda sensação é o assunto deste livro.

trabalho bagunçado entra, trabalho pronto sai, os passos no meio atrás de um vidro fosco
Figura 1 O trabalho bagunçado entra por um lado de uma parede de vidro fosco e o trabalho pronto sai pelo outro; os passos no meio são apenas silhuetas. O encanto é imediato. A dúvida dura mais que ele, e é o assunto deste livro.

Escrevi este livro para quem trabalha com engenharia no dia a dia — alguém à vontade com software, mas não necessariamente com aprendizado de máquina — que está avaliando agentes, ou acabou de começar a construir com eles, e quer deixar para trás tanto o hype quanto o pavor e chegar à engenharia que está por baixo. Você vai encontrar definições construídas a partir dos primeiros princípios, padrões que se repetem em todos os domínios em que agentes fazem trabalho útil, exemplos em pseudocódigo simples e um interesse persistente em quanto as coisas custam e em como elas falham. O único pré-requisito é a bagagem normal de quem trabalha com engenharia; sempre que aparece um termo técnico, eu o defino na hora, em palavras simples.

Duas promessas moldam todos os capítulos, e quero deixá-las explícitas, porque juntas elas explicam o que você vai e o que não vai encontrar aqui.

A primeira promessa é que o livro é agnóstico quanto ao tempo. Esta área avança em um ritmo que constrange qualquer um que ponha as coisas no papel; enquanto eu reunia material para estes capítulos, anotações que eu tinha feito poucos meses antes já estavam ficando velhas, com produtos rebatizados e números de benchmark superados. Por isso me recusei a ancorar qualquer coisa na época em que foi escrita. Nenhuma afirmação deste livro depende de qual modelo é o melhor no momento, de quanto custa um token neste trimestre ou do tamanho das janelas de contexto deste ano. Onde aparece um número, ele está marcado como ilustração. O objetivo é um livro que se leia tão bem daqui a alguns anos quanto hoje.

A segunda promessa é que ele é agnóstico quanto à solução. O conhecimento durável desta área está em conceitos e padrões — o loop, o contrato da ferramenta, o orçamento de contexto, a suíte de avaliação — e esses valem para qualquer fornecedor e qualquer framework. A sintaxe de um produto específico não se transfere, e envelhece em meses. Por isso este livro ensina o padrão e cita ferramentas concretas só de passagem, como exemplos, assim identificados, de uma categoria. Ao terminar, você deve ser capaz de se sentar diante de qualquer harness (a casca de software dentro da qual um agente roda) que a sua equipe tenha adotado, ou diante de nenhum, e saber o que construir.

Uma ideia volta tantas vezes nestas páginas que equivale a uma tese, e é bom que você a conheça desde já: um agente só é tão confiável quanto o sinal que você tem para verificá-lo. Um modelo de linguagem produz texto fluente e seguro de si, esteja certo ou errado; o tom dele não diz nada em que você possa se apoiar. A confiança que você deposita em um agente, portanto, tem de vir de algum lugar fora do modelo: uma suíte de testes que passa, um schema que valida, uma fonte que você pode abrir e conferir, um humano que aprova o passo irreversível. Onde existe um sinal desses, você pode conceder autonomia com generosidade — e é em boa parte por isso, como veremos, que a programação se tornou o primeiro domínio em que os agentes provaram seu valor, já que o código chega com o próprio veredito: compile, rode os testes. Onde não existe sinal, a autonomia é um salto de fé, e este livro vai continuar dizendo isso. Quase toda questão de projeto nos capítulos adiante se resolve com o mesmo primeiro movimento: perguntar que sinal indica que deu certo.

Uma palavra sobre vocabulário. “Agente” talvez seja o termo mais sobrecarregado do software moderno; ele é aplicado com a mesma segurança a um bot de roteiro fixo que percorre um menu de atendimento telefônico e a um sistema em que se confia para trabalhar sozinho por uma tarde inteira. Jargão só é útil quando quem fala e quem ouve compartilham uma definição; do contrário, duas pessoas podem discutir apaixonadamente coisas completamente diferentes.1 Simon Willison, “I think ‘agent’ may finally have a widely enough agreed upon definition to be useful jargon now”, simonwillison.net (setembro de 2025). A observação sobre o jargão compartilhado e a definição prática que este livro adota no capítulo 1 são dele. Por isso o primeiro capítulo faz o trabalho pouco glamoroso de fixar os termos, e o resto do livro se mantém fiel a eles.

Sobre como ler o livro: ele está dividido em sete partes, ordenadas como um curso. A Parte I estabelece o que é um agente e como o motor que está por baixo — o modelo de linguagem — realmente funciona. As Partes II e III constroem um: o loop, as ferramentas, as habilidades (skills) reutilizáveis e a gestão cuidadosa da memória de trabalho do modelo. A Parte IV trata de arquitetura: workflows, sistemas multiagente, o dial entre supervisão e autonomia, o ofício de escrever o loop externo do harness e a disciplina de perguntar se a coisa mais simples que funciona precisa mesmo de um agente. As Partes V e VI cobrem aquilo que acaba sendo a maior parte da engenharia de agentes na vida real: avaliação, observabilidade, segurança, confiabilidade, custo e implantação. A Parte VII se volta para as aplicações e para o que parece durável no caminho à frente. Os apêndices trazem um agente mínimo em pseudocódigo comentado, um glossário e um mapa de leituras complementares. Leia as partes em ordem para ter uma base ou, depois de se orientar, consulte-as como obra de referência; os capítulos remetem uns aos outros e procuram se sustentar sozinhos.

Preciso ser honesto sobre o que um livro como este pode prometer. Alguns detalhes daqui serão superados, provavelmente mais cedo do que eu gostaria; procurei escrever apenas as partes que sobrevivem aos próprios exemplos e sinalizar minha incerteza onde ela existe. A aposta deste livro é que princípios duram mais que produtos. Se, daqui a alguns anos, os exemplos parecerem antiquados, mas as perguntas — que sinal verifica isto? qual é a coisa mais simples que funciona? — continuarem sendo as que você faz, o livro terá cumprido seu papel.

Um pedido antes de começar. Se você quiser me contar como este livro chegou até você, há uma página para isso: leva um clique, é anônima e não pede e-mail: aiagentsengineered.com/found. Um livro como este não tem departamento de marketing, e essa resposta me diz onde investir o pouco tempo que tenho para contar a outros engenheiros que ele existe.