Como funcionam agentes de IA de verdade?

Agentes de IA são softwares que usam uma LLM como cérebro para decidir, a cada turno, qual ação executar de forma autônoma. Diferente de uma chamada comum via SDK, o comportamento é probabilístico: o agente conversa com o modelo, executa tools, devolve resultados e só então responde ao usuário. Neste artigo você entende o ciclo completo, do RAG ao Google ADK.

O que são agentes de IA — e o que não são

Agentes de IA são softwares que usam uma LLM como cérebro para decidir, em múltiplos turnos, qual ação executar de forma autônoma. A LLM é stateless: não guarda estado e não executa nada. O agente é o corpo — envia todo o histórico ao modelo, recebe uma instrução, executa e devolve o resultado, repetindo o ciclo até o modelo devolver uma resposta final.

A distinção mais valiosa da aula: se seu código faz uma única chamada via SDK da OpenAI ou do Google, ele continua sendo um software determinístico, com ifs e laços programados passo a passo. Isso não é um agente. O chatbot tradicional também não é, porque não tem LLM nem autonomia. E o n8n, embora tenha recebido nós de agente recentemente, é por padrão um fluxo determinístico.

Outro ponto recorrente: a interface não é o agente. Chat, CLI, desktop ou front-end web são apenas capas de acesso. O mesmo agente pode servir às quatro. Na prática, ferramentas como o Claude Code e o GitHub Copilot são plataformas completas de agentes que você usa como usuário final — desenvolver agentes é um papel diferente.

Um agente típico carrega quatro recursos: um system prompt que define o domínio, tools para ler arquivos ou chamar APIs, skills que estendem conhecimento e servidores MCP que conectam plataformas externas. A recomendação dos instrutores é clara: agentes focados em um domínio específico. Um agente que abre ticket, resolve ticket e consulta CRM ao mesmo tempo fica difícil de manter, testar e trocar de modelo.

RAG é uma pipeline, não uma feature

RAG (retrieval augmented generation) resolve um problema concreto: a janela de contexto da LLM é limitada. Colocar as 600 páginas de um livro como o Domain-Driven Design de Eric Evans no prompt consumiria em torno de um milhão de tokens, e fine-tuning é caro. O RAG busca apenas os trechos relevantes antes de responder.

O conceito cabe em três passos: buscar informações relevantes em uma base de conhecimento, enriquecer o contexto com elas e gerar a resposta. Mas a execução é uma pipeline com dois momentos distintos. Na ingestão, você quebra documentos em chunks, extrai metadados e indexa em um banco vetorial. Na pergunta, você busca trechos candidatos, monta o contexto e chama o modelo.

Há serviços gerenciados que montam essa arquitetura, como o Amazon Bedrock Knowledge Bases, o Azure AI Search da Microsoft e o File Search da OpenAI. A lição dos instrutores, porém, vale para qualquer provedor: as decisões de chunking, ranqueamento e organização continuam suas. RAG pode fazer parte de um agente, mas não é um agente por si só.

Uma observação honesta: RAG também pode existir sem IA, como busca semântica pura em um software tradicional. O que muda no cenário agêntico é que a pesquisa passa a ser uma tool. O agente pergunta à LLM, o modelo pede a busca, o agente executa e devolve — e a LLM pode decidir buscar mais um trecho antes de responder.

Ingestão, chunks e busca semântica no banco vetorial

A busca léxica tradicional do SQL compara caractere a caractere e falha quando o usuário escreve o termo errado. O banco vetorial permite busca semântica: em vez de igualar strings, ele encontra trechos com significado próximo à pergunta. É a mesma lógica de há tempos usada pelo Google quando corrige erros de digitação.

No exemplo didático da aula, o processo segue um roteiro simples em Python: carregar os documentos com metadados no topo (título, plano, versão, visibilidade), dividir por seções e depois por trechos menores, gerar um cabeçalho que torne cada chunk compreensível fora do arquivo original e indexar no Postgres com a extensão pgvector. Oito arquivos geraram 134 chunks nesse exemplo. Alternativas como o Pinecone (pinecone.io) existem, mas o pgvector aparece como escolha do MBA da Full Cycle.

Como a busca responde com fontes rastreáveis

Cada chunk guarda sua origem nos metadados. Quando o usuário pergunta, por exemplo, qual é o SLA para incidentes P1 no plano Enterprise, a pipeline retorna os trechos candidatos com score e fonte. O resultado final cita de onde cada informação veio, o que viabiliza auditoria e confiança na resposta.

Rerank e query planner: o trabalho do engenheiro

Buscar retorna muito material ruim. O rerank seleciona os trechos mais relevantes entre os candidatos — no projeto mostrado, quatro entre oito. Detalhe importante: esse rerank não gera resumo nem reduz texto; ele só escolhe os itens mais relevantes para a pergunta, com um prompt dedicado.

Antes da busca, um query planner reescreve a pergunta preservando termos específicos, sugere filtros de conteúdo e a aplicação acrescenta filtros determinísticos de segurança, como produto e status. A pipeline madura fica assim: planejamento da busca, guardrails, busca de candidatos, rerank, montagem de contexto e resposta da LLM.

Essa é a parte que ninguém abstrai por você: decidir como inserir, pontuar e organizar os dados é trabalho de engenharia. Serviços gerenciados ajudam, mas quem define a qualidade da recuperação é quem desenha a pipeline.

LangGraph: orquestrando agentes por grafos

LangChain e LangGraph são frameworks de duas camadas do mesmo ecossistema. O LangGraph, camada de baixo, controla o fluxo por nós e arestas, com estados compartilhados. O LangChain é a camada mais simples, em que criar um agente é praticamente uma função — e não está depreciado; é apenas uma abordagem menos explícita.

O exemplo da aula é um agente de code review com três nós: um analyzer que avalia complexidade e code smells, um summarizer que descreve o código e um reviewer final. Start e wait for both garantem que os dois primeiros rodem em paralelo e que o reviewer só execute quando ambos terminarem. O fluxo espera os dois caminhos, levem eles um segundo ou dez minutos.

Cada tool é uma função Python com um decorator — e pode conter código determinístico, chamadas externas via MCP ou lógica de negócio, não apenas LLM. A observabilidade fica por conta do LangSmith, que mostra traces e permite evals, com camada gratuita; o Langfuse é a alternativa open source. No trace, você vê cada chamada de tool, o input e o texto estruturado devolvido por cada agente.

Google ADK: seu primeiro agente em poucas linhas

O Google ADK (Agent Development Kit) é o framework do Google para criar agentes, usado internamente pela empresa antes de virar open source. Na aula, ministrada em setembro de 2026, ele aparecia na versão 2.9 do pacote Python — sempre a mais atualizada — com o Java em 1.10. Suporta Python, Java, Go e outras linguagens, com integrações prontas com Vertex AI e Google Cloud.

O agente mínimo não tem system prompt nem tools: basta importar a classe Agent, dar um nome e atribuir à variável root_agent, convenção que o framework espera. Rodando com adk run, um modelo da família Gemini Flash responde por padrão. Já o adk web sobe uma interface de debug na porta 8000 que revela a request exata enviada ao modelo — incluindo um system prompt implícito que o ADK monta sozinho.

Para chaves de API, o caminho é o Google AI Studio: os modelos Flash têm cotas gratuitas, tipicamente em torno de cinco chamadas por minuto em alguns modelos, suficientes para estudar. Para modelos de outros provedores, o LiteLLM funciona como biblioteca coringa de interface única.

Tools, confirmação e sessões

No agente de operações de conta do exemplo, duas tools ilustram boas práticas: nome e argumentos sugestivos, docstrings, tipos declarados e retorno em dicionário com status e mensagem — tudo isso vira contexto para a LLM. A tool de cancelamento usa um mecanismo de confirmação: ela interrompe a execução, pede aprovação ao usuário e só conclui depois do confirm igual a true, o mesmo padrão de aprovação de comandos que você vê no Claude Code.

Em aplicações web, o ADK se apoia no FastAPI, que já vem integrado. O padrão exige criar sessão, instanciar content e runner e iterar sobre os eventos até achar o final response. O instrutor lembra o fundamento: chamadas HTTP são bloqueantes, e o padrão de event loop com asyncio permite atender 100 usuários simultâneos sem travar a API.

Perguntas frequentes

• Chatbot é um agente de IA? Não necessariamente. Um chatbot tradicional é determinístico e pode nem usar LLM. Você pode construir um chatbot que seja agente, mas a interface de conversa por si só não define a autonomia.

• RAG substitui o fine-tuning? No caso apresentado, sim como alternativa prática: treinar um modelo é caro e o RAG entrega contexto relevante sob demanda. A escolha depende do domínio, do custo e da frequência de atualização da base.

• Qual framework usar para começar? O Google ADK tem curva de aprendizado menor e integrações prontas com Gemini e Google Cloud; LangGraph oferece controle fino por grafos para fluxos complexos. Os conceitos de tools, sessões e turnos se transferem entre frameworks.

• Como controlar pedidos fora do escopo do agente? Com guardrails: um hook antes da chamada pode classificar a intenção com uma LLM barata (padrão LLM as a judge) ou aplicar filtros determinísticos, devolvendo uma resposta fora de escopo sem gastar tokens do modelo principal.

• Como reduzir o custo de token em produção? Observabilidade primeiro, com tracing de custos via OpenTelemetry ou plataformas como Datadog. Depois, cache bem configurado (prompt estável gera fingerprint reutilizável), modelos Flash para tarefas simples, processamento em lote quando a latência não importa e RAG para enviar apenas o contexto útil.

Do vídeo ao artigo: transforme esse conhecimento

A aula que originou este texto saiu do canal Dev Doido da Full Cycle e destilou horas de código em conceitos aplicáveis — o mesmo raciocínio vale para o Crazystack TypeScript (crazystack.com.br) e para qualquer aula técnica gravada. Se você também tem conhecimento valioso preso em vídeos, seja uma live de agentes de IA ou um estudo de caso, transformar esse material em artigo escrito amplia seu alcance sem refazer o trabalho.

O Skala Blog faz exatamente isso: você cola a URL do YouTube, o conteúdo é transcrito e vira um artigo estruturado, pronto para revisão e publicação.

Source video