Todo mundo quer um agente de IA rodando. Pouca gente entende a anatomia. Sem essa clareza, o time monta um chatbot com prompt grande, chama de agente, e descobre em três meses que o sistema responde rápido, inventa fato, ignora dado novo e não executa ação nenhuma fora da conversa.
Este post abre o capô. Você vai entender o que é um agente de verdade, por que ele precisa de RAG (Retrieval-Augmented Generation), como um banco vetorial faz a busca semântica acontecer, e como tudo se conecta no fluxo de execução. Sem misticismo, só engenharia.
O que é um agente: o loop por trás do hype
Um agente não é um modelo. Um agente é um loop estruturado em torno do modelo. O LLM raciocina e decide; o resto do sistema (memória, ferramentas, validação, controle de fluxo) executa. Sem esse arcabouço, você tem um gerador de texto bonito, não um agente.
O loop básico tem quatro fases: (1) percepção (recebe input do usuário ou de outro sistema), (2) raciocínio (o LLM analisa contexto, recupera memória, escolhe a próxima ação), (3) execução (chama uma tool, consulta um banco, escreve em API), (4) observação (lê o resultado e decide se continua, termina ou pede ajuda). O loop repete até a tarefa fechar ou o budget acabar.
Três variações se sustentam em produção: agente reativo (um passo, decisão simples), agente com plano (gera plano, executa por etapas, replaneja quando algo falha) e agente multiagente (vários papéis especializados conversando entre si, com um orquestrador). Comece pelo reativo. A maioria dos casos reais resolve no primeiro nível e te ensina o que importa antes de você complicar.
RAG: por que o agente precisa de memória externa
O LLM tem conhecimento congelado no treinamento. Ele não sabe o nome do seu cliente, o histórico do ticket, o conteúdo do PDF que você subiu ontem. Tudo isso é dado externo. Pra entrar no raciocínio do agente, esse dado tem que ser recuperado e injetado no prompt em tempo de execução. Esse é o coração do RAG.
RAG significa Retrieval-Augmented Generation. O agente não tenta lembrar, ele busca. A cada turno, antes de raciocinar, o sistema consulta uma base de conhecimento, traz os trechos relevantes e adiciona ao contexto enviado ao LLM. O modelo então gera a resposta com fundamento, citando ou referenciando a fonte, em vez de inventar.
RAG resolve três problemas que prompt sozinho não resolve. Atualização: você indexa documentos novos a qualquer momento, sem retreinar modelo. Escala: o LLM não precisa ter visto seu corpus inteiro, só precisa ler o trecho relevante. Auditoria: a resposta cita a fonte, então humano valida e o time confia.
Vector database: como a busca semântica funciona
O banco vetorial é a infraestrutura que faz o RAG escalar. Em vez de buscar por palavra-chave (que ignora sinônimo e contexto), você busca por similaridade semântica entre o que o usuário pediu e o que está indexado.
Funciona assim. Cada pedaço de texto (chunk) é convertido em um vetor numérico de alta dimensão (768, 1024 ou 1536 dimensões, dependendo do modelo de embedding). Esse vetor representa o significado do texto num espaço matemático. Quando o usuário pergunta algo, a pergunta também vira vetor, e o banco retorna os k vetores mais próximos por distância (cosseno, euclidiana ou produto interno).
Escolhas que importam: modelo de embedding (OpenAI text-embedding-3-large, Cohere embed v4, BGE para self-hosted), banco vetorial (Qdrant para self-hosted, Pinecone para managed, pgvector se você já tem Postgres, Weaviate quando precisa de filtro híbrido) e estratégia de indexação (HNSW para velocidade, IVF para volume gigante, exato para datasets pequenos). Não existe escolha universal, existe escolha justificada por requisito de latência, volume e custo.
Pipeline de ingestão: do documento ao chunk indexável
Ingestão é onde a maioria dos agentes RAG morre antes mesmo de subir. O dataset bruto raramente é o que entra no banco. Você precisa de um pipeline com etapas claras.
(1) Parsing: extrair texto limpo de PDFs, planilhas, HTML, transcrição de áudio. Ferramentas como Unstructured, LlamaParse e Docling fazem o trabalho pesado, mas sempre exigem revisão por tipo de documento. (2) Chunking: quebrar em pedaços com tamanho útil (300 a 800 tokens funciona pra maioria dos casos), respeitando fronteiras semânticas (parágrafo, seção, nunca corte no meio da frase). (3) Enriquecimento: adicionar metadados (fonte, data, autor, tags, ACL) que o agente pode filtrar depois. (4) Embedding: passar cada chunk pelo modelo escolhido e armazenar o vetor junto com o texto e os metadados. (5) Indexação: salvar no vector DB com o índice apropriado.
Um detalhe que separa amador de profissional: reindexação contínua. Documentos mudam, modelos de embedding evoluem, estratégia de chunking precisa ser revisitada. Trate seu índice como código: versão, testes, rollback. Sem isso, você fica preso na primeira escolha errada e descobre tarde demais.
Tool calling: o que diferencia agente de chatbot
Chatbot fala. Agente age. Tool calling é o mecanismo que dá mãos ao LLM: você define um conjunto de funções (cada uma com nome, descrição e schema de entrada), o modelo escolhe qual chamar e com que argumentos, seu código executa de verdade, devolve o resultado, e o ciclo continua.
Tools comuns num agente sério: search_knowledge_base (faz a recuperação RAG), query_database (consulta dados estruturados), call_external_api (integra com CRM, ERP, sistemas internos), execute_code (sandbox seguro para cálculo ou transformação), write_action (cria ticket, envia email, agenda reunião). Cada tool é validada por schema e tem retry, timeout e log próprios.
Protocolos modernos como MCP (Model Context Protocol) padronizam como o agente descobre e chama tools entre sistemas. Adotar MCP cedo evita refazer integração para cada modelo novo e abre porta pra usar tools de terceiros sem reescrever cliente.
Do prompt à ação: o fluxo end-to-end
Veja o caminho completo de uma pergunta real até a ação. Usuário pergunta no chat interno: qual a margem do contrato 4421 no último trimestre?. O agente recebe, passa pelo planner, identifica que precisa de dois dados: o contrato (estruturado, no banco SQL) e a regra de cálculo de margem (não estruturada, no manual de finanças em PDF).
Tool 1: query_database(contract_id=4421, period=Q3) traz o valor bruto. Tool 2: search_knowledge_base(query="cálculo de margem para contratos do tipo X") faz embedding da pergunta, consulta o vector DB, retorna os três chunks mais relevantes do manual. O LLM agora tem dado bruto e regra de cálculo no contexto, faz o cálculo, formata a resposta com a fonte citada (página do manual, ID do contrato) e responde. Tudo em segundos, com auditoria do raciocínio gravada.
Esse é o padrão que escala: o agente decide quando usar RAG, quando usar consulta estruturada e quando só responder direto. RAG não é resposta pra tudo, é uma ferramenta no cinto.
Erros que matam agentes RAG em produção
Chunks grandes demais: o trecho irrelevante polui o contexto e o modelo se confunde. Chunks pequenos demais: perde contexto, recupera fragmento sem sentido. Embedding único pra tudo: domínio jurídico, técnico e conversacional pedem modelos diferentes (ou fine-tuning de embedding). Sem reranker: a primeira recuperação raramente é ótima, um reranker (Cohere Rerank, BGE-reranker) eleva precisão muito. Sem feedback loop: você não sabe quando o agente errou se não logar query, contexto recuperado, resposta gerada e amostragem de julgamento humano.
E o mais comum: falta de avaliação. Agente sem golden set, sem métrica de retrieval (recall@k, MRR, NDCG), sem teste de regressão, vira aposta. Você empurra prompt novo no escuro, quebra coisa, descobre quando o cliente reclama. Avaliação não é opcional, é o que separa agente que escala de demo bonito que morre no segundo mês.
Agente é arquitetura, não modelo
O LLM virou commodity. Custa centavos por milhão de token e melhora a cada release. O que diferencia um agente que funciona de um que falha não é o modelo escolhido, é a arquitetura ao redor dele: pipeline de ingestão sólido, vector DB bem configurado, tools com schema disciplinado, observabilidade desde o dia zero e feedback contínuo.
Construir agente é engenharia de sistemas distribuídos com uma peça nova no meio. Trate como engenharia, não como prompt engineering com cara nova, e seu agente vai durar.
