Anatomia de um agent de IA: memória, ferramentas e loops de decisão

A Confusão Que Custa Meses aos Times

Toda semana, conversamos com um CTO ou líder de engenharia que diz estar “construindo agents.” Aí fazemos três perguntas:

1. Ele lembra o que aconteceu ontem?
2. Ele consegue tomar ações sem seu código explicitamente chamar uma API?
3. Ele consegue decidir o que fazer a seguir sem um humano escolhendo o passo?

Se a resposta para todas as três é não, você não construiu um agent. Você construiu uma cadeia de prompts. E tudo bem, cadeias de prompts são úteis. Mas confundir uma cadeia de prompts com um agent é como times gastam seis meses construindo algo que não faz o que prometeram.

Um agent são três coisas: memória, ferramentas e um loop de decisão. Remova qualquer uma, e você tem algo diferente, algo potencialmente valioso, mas não um agent. Entender esses três componentes e como interagem é a diferença entre construir sistemas que realmente funcionam e construir auto-complete elaborado.

É assim que construímos agents na Apollo Space. Não teoria, implementação.

Componente 1: Memória

A parte mais mal compreendida da arquitetura de agents é memória. A maioria dos times confunde memória com context windows, e a confusão é cara.

Uma context window é o texto que você passa ao LLM em cada chamada. É o prompt, a conversa recente, os documentos recuperados. É o que o modelo vê agora. Quando a chamada termina, a context window desaparece. O modelo não tem conhecimento de que a conversa aconteceu.

Memória é o que persiste entre chamadas. É o conhecimento acumulado, a experiência e os procedimentos do agent. É o que permite ao agent melhorar com o tempo, reconhecer padrões e agir com informação de semanas ou meses atrás.

Implementamos três tipos de memória nos agents da Apollo Space, emprestando terminologia da ciência cognitiva:

Memória Episódica: O Que Aconteceu

Memória episódica armazena eventos, coisas específicas que aconteceram, quando aconteceram e qual foi o resultado. É a autobiografia do agent.

Para o agent SDR da Apollo Space, memória episódica parece assim:

Evento: Enviou email de prospecção para VP de Engenharia da AcmeCorp
Data: 2026-01-14 09:32:00
Ação: Cold email, personalizado sobre Series B recente
Resultado: Aberto, sem resposta
Follow-up: Agendado para 2026-01-18

Evento: Enviou follow-up para VP de Engenharia da AcmeCorp
Data: 2026-01-18 14:15:00
Ação: Follow-up referenciando vaga de DevOps lead
Resultado: Resposta recebida, positiva, reunião agendada para 2026-01-22
Follow-up: Prep de reunião acionado

Isso não é um log de conversa. É um registro estruturado de ações e resultados que o agent pode consultar. Quando o agent SDR está decidindo como abordar um novo prospect, ele não usa apenas o contexto atual, consulta sua memória episódica para prospects similares, estratégias de outreach similares e seus resultados.

A consulta pode ser: “Mostre as últimas 20 sequências de outreach para prospects VP-level em empresas Series B no espaço de developer tools, ranqueadas por taxa de conversão em reunião.” Os resultados informam a estratégia do agent para o próximo prospect.

Memória episódica é armazenada num banco de dados vetorial (usamos Qdrant) com metadados estruturados. Cada episódio é embutido para busca por similaridade semântica e taggeado com campos estruturados (resultado, atributos do prospect, estratégia usada) para consultas filtradas. A combinação de busca semântica e estruturada é importante, busca puramente semântica retorna eventos similares, mas filtros estruturados permitem que o agent faça perguntas analíticas precisas sobre sua própria história.

Memória Semântica: O Que É Verdade

Memória semântica armazena fatos e conhecimento, coisas que o agent sabe que não estão ligadas a eventos específicos. É o entendimento do agent sobre o mundo.

Para o agent de competitor watch, memória semântica inclui:

• Tiers de preço e breakdown de features atuais da CompeteLogic
• O CTO da AcmeCorp trabalhou anteriormente na Datadog (e portanto provavelmente valoriza features de observabilidade)
• Q4 é historicamente o trimestre mais lento para compras de tecnologia de empresas de logística
• Nossa taxa de vitória contra a CompeteLogic é 62% quando lideramos com estabilidade de preços

Esse conhecimento é acumulado ao longo do tempo a partir da memória episódica do agent (padrões extraídos de eventos), fontes de dados externas e contexto fornecido por humanos. É atualizado conforme novas informações chegam, quando a CompeteLogic muda seus preços, a memória semântica atualiza imediatamente.

A distinção entre memória episódica e semântica importa para recuperação. Quando o agent SDR está se preparando para uma ligação, precisa de ambas: memória episódica diz o que aconteceu em interações anteriores com este prospect, e memória semântica diz o que é verdade sobre a indústria do prospect, sua empresa e dinâmicas competitivas.

Armazenamos memória semântica como um knowledge graph com arestas ponderadas. Entidades (empresas, pessoas, produtos, conceitos) são nós. Relacionamentos (compete-com, trabalha-em, prefere, costumava-usar) são arestas com scores de confiança. Os scores de confiança decaem com o tempo, um fato de seis meses atrás é menos confiável que um fato de ontem, o que previne o agent de agir com informação desatualizada sem ser avisado.

Memória Procedural: O Que Fazer

Memória procedural armazena como fazer coisas, procedimentos aprendidos, heurísticas e frameworks de decisão. É a memória muscular do agent.

Esse é o tipo de memória menos intuitivo porque parece que deveria ser código. E parte é, procedimentos hardcoded, conjuntos de regras explícitos, sequências de chamadas de API. Mas a memória procedural mais valiosa é aprendida, não codificada.

Por exemplo, o agent de QA da Apollo Space tem uma entrada de memória procedural que diz:

Procedimento: Testando mudanças em middleware de auth
Aprendido de: Bug #1847 (Novembro 2025) — loop de redirect no login
Passos:
  1. Testar o happy path (fluxo padrão de login)
  2. Testar com sessões expiradas
  3. Testar com provedores SSO se código SSO está no diff
  4. CRÍTICO: Testar comportamento de redirect para usuários
     não autenticados acessando rotas protegidas — este é o modo
     de falha mais comum para mudanças em middleware de auth
  5. Testar com múltiplas sessões concorrentes
Confiança: 0.94
Última validação: 2026-02-15

Esse procedimento não foi escrito por um humano. Foi extraído da memória episódica do agent após pegar um bug de redirect no login. O agent identificou o padrão, mudanças em middleware de auth frequentemente quebram comportamento de redirect, e codificou como um procedimento de teste reutilizável.

Memória procedural é o mecanismo pelo qual agents melhoram no seu trabalho ao longo do tempo. Cada resultado significativo (especialmente falhas) é analisado, e se um procedimento generalizável pode ser extraído, é adicionado à memória procedural. Ao longo de meses, isso se acumula em algo que parece notavelmente com expertise.

Armazenamos memória procedural como procedimentos estruturados com scores de confiança, gatilhos de contexto (quando aplicar este procedimento) e timestamps de validação. Procedimentos que não foram validados em 90 dias são flaggados para revisão, e procedimentos cuja confiança cai abaixo de 0,7 (devido a resultados contraditórios) são aposentados.

Componente 2: Ferramentas

Memória dá aos agents conhecimento. Ferramentas dão aos agents poder.

Uma ferramenta, na arquitetura de agents, é qualquer função que o agent pode chamar para agir no mundo ou recuperar informação dele. Ferramentas são a ponte entre raciocínio e ação.

Os agents da Apollo Space têm acesso a ferramentas em quatro categorias:

Ferramentas de Informação

Recuperam dados que o agent não tem em memória. Exemplos:

• Consultar o CRM para histórico de engajamento de um prospect
• Buscar na web notícias recentes sobre uma empresa
• Ler um diff de PR no GitHub
• Verificar métricas atuais do sistema no stack de observabilidade

Ferramentas de Ação

Mudam o estado do mundo. Exemplos:

• Enviar um email
• Postar uma mensagem no Slack
• Criar um ticket no JIRA
• Aprovar ou solicitar mudanças num PR no GitHub

Ferramentas de Análise

Realizam computação que o LLM não consegue fazer confiavelmente sozinho. Exemplos:

• Rodar análise estatística em taxas de conversão do pipeline
• Calcular impacto financeiro de uma variância orçamentária
• Comparar dois snapshots de código para diferenças comportamentais
• Dar score a um lead contra os critérios de ICP

Meta Ferramentas

Permitem que o agent gerencie a si mesmo. Exemplos:

• Escrever na própria memória
• Ajustar seus thresholds de confiança
• Escalar para um humano
• Solicitar mais informação antes de prosseguir

O design das ferramentas importa mais do que a maioria dos times percebe. Um erro comum é dar aos agents ferramentas granulares demais (enviar um request HTTP) ou abstratas demais (fazer a coisa certa). O nível certo de abstração é o nível no qual um humano competente descreveria a ação. Não “construa um request POST para a API do Slack com este payload JSON” mas “envie uma mensagem para o canal #vendas dizendo que o deal com AcmeCorp foi atualizado.”

Cada ferramenta tem três propriedades de metadados que o agent usa ao planejar:

1. Reversibilidade: Esta ação pode ser desfeita? Enviar uma mensagem no Slack tem baixa reversibilidade. Criar um documento rascunho tem alta reversibilidade. O agent considera reversibilidade na sua tomada de decisão, está mais disposto a tomar ações de alta reversibilidade sem aprovação humana.

2. Custo: Qual o custo de usar esta ferramenta? Não apenas custo de computação, mas custo de atenção (enviar uma notificação interrompe alguém) e custo de reputação (enviar um email ruim danifica um relacionamento). O agent pondera custo contra valor esperado antes de agir.

3. Latência: Quanto tempo esta ferramenta leva para retornar resultado? Uma consulta ao CRM leva milissegundos. Uma busca web leva segundos. Rodar uma suíte de testes de QA leva minutos. O agent planeja suas ações para paralelizar chamadas de ferramentas de alta latência quando possível.

Componente 3: O Loop de Decisão

Memória é conhecimento. Ferramentas são capacidade. O loop de decisão é o mecanismo que transforma conhecimento e capacidade em ação autônoma.

Todo agent da Apollo Space roda o mesmo loop de decisão central, que chamamos de PRAO: Perceber, Raciocinar, Agir, Observar.

Perceber

O agent recebe input do seu ambiente. Pode ser:

• Um evento gatilho (um novo PR foi aberto, um timer agendado disparou, uma mensagem do Slack foi recebida)
• Uma mensagem de outro agent (o agent de competitor watch detectou uma mudança de preço)
• Um pedido humano (um usuário pediu ao agent para fazer algo)

Percepção não é recepção passiva, inclui filtragem e priorização. O agent SDR recebe dezenas de sinais por hora: aberturas de email, cliques em links, atualizações de CRM, mudanças de calendário. Percepção é o estágio onde o agent decide quais sinais são relevantes agora.

Implementamos percepção como uma fila de prioridade com scoring de relevância. Cada sinal de entrada é pontuado baseado nos objetivos atuais do agent, na urgência do sinal (sensível ao tempo vs. pode esperar) e no impacto esperado do sinal (quanto agir neste sinal mudaria resultados). Apenas sinais acima do threshold de relevância entram no estágio de raciocínio.

Raciocinar

O agent decide o que fazer. É aqui que o LLM ganha seu salário.

Raciocínio pega o sinal percebido, recupera memória relevante (episódica: o que aconteceu em situações similares; semântica: o que é verdade sobre este contexto; procedural: qual a abordagem padrão), coleta informação adicional via ferramentas e produz um plano.

O plano não é uma única ação, é uma sequência de ações com ramificações condicionais. “Envie um email de follow-up. Se o prospect responder em 48 horas, agende uma reunião. Se não responder, espere 5 dias e tente um ângulo diferente. Se responder negativamente, registre a objeção e arquive a sequência.”

A decisão de engenharia crítica no estágio de raciocínio é o que entra na context do LLM. A context window é finita (e cara), então não podemos despejar todas as memórias e resultados de ferramentas em cada chamada de raciocínio. Usamos uma estratégia de recuperação que combina:

• Memória episódica ponderada por recência: Eventos recentes sobre este prospect/projeto/sistema específico
• Memória semântica ponderada por similaridade: Fatos relevantes para a situação atual
• Memória procedural por gatilho: Procedimentos que correspondem ao contexto atual
• Resultados de ferramentas: Dados frescos recuperados no estágio de percepção

O contexto total é tipicamente 4.000-8.000 tokens de memória mais o sinal atual. Descobrimos que mais contexto não melhora confiavelmente a qualidade do raciocínio, a relação sinal-ruído degrada, e o agent começa a prestar atenção em detalhes irrelevantes. Precisão na construção de contexto importa mais que volume.

Agir

O agent executa seu plano chamando ferramentas. Cada ação é registrada na memória episódica com timestamp, o raciocínio que levou a ela e o resultado esperado.

O principal desafio de engenharia no estágio de ação é tratamento de erros. O que acontece quando uma chamada de ferramenta falha? O que acontece quando a ação produz um resultado inesperado? O que acontece quando o plano do agent tem um passo que depende do resultado de um passo anterior que não foi como esperado?

Lidamos com isso com um mecanismo de replanejamento. Após cada ação, o agent compara o resultado real contra o resultado esperado. Se divergem significativamente, o agent re-entra no estágio de raciocínio com a nova informação. Esse é o “loop” em “loop de decisão”, não é um pipeline linear, é um ciclo iterativo.

O mecanismo de replanejamento tem circuit breakers. Se o agent replaneja mais de três vezes num único ciclo de decisão, ele escala para um humano. Isso previne loops infinitos onde o agent fica tentando a mesma abordagem falhando com variações menores.

Observar

Após agir, o agent observa o resultado. O email foi enviado? O teste passou? As métricas do sistema mudaram? Observação fecha o loop e alimenta a memória.

Observação também é onde o agent atualiza seu próprio modelo de eficácia. Se previu que uma estratégia particular de outreach teria 30% de taxa de resposta e a taxa real no último mês é 45%, atualiza seu modelo preditivo. É assim que agents calibram sua confiança ao longo do tempo, não através de retreinamento explícito, mas através de observação contínua e ajuste.

Chamadas Stateless vs. Agents Stateful

Vamos tornar a diferença concreta com um exemplo.

Chamada stateless de LLM: Você envia ao modelo o perfil do LinkedIn de um prospect e pede para escrever um cold email. O modelo escreve um email genérico personalizado. Bom o suficiente. Mas ele não sabe que você enviou email para esse prospect três semanas atrás. Não sabe que prospects nessa indústria respondem melhor a emails com case studies. Não sabe que a empresa do prospect acabou de fazer uma rodada de investimento. Cada chamada começa do zero.

Agent stateful: O agent SDR vê um gatilho (novo prospect adicionado ao CRM). Consulta memória episódica (nunca contatamos essa pessoa, mas contatamos um colega dela no Q4, sem resposta). Consulta memória semântica (fintech Series B, 80 funcionários, CTO ex-Stripe, alto fit de ICP). Recupera memória procedural (prospects fintech respondem 2,3x melhor a emails focados em ROI que em features; melhores horários de envio para esse segmento são terça/quarta 9-10h). Raciocina sobre a abordagem, redige o email, envia no horário ideal, registra a ação e agenda o follow-up.

O email do agent stateful não é apenas personalizado, é informado por meses de experiência acumulada. Isso não é um prompt melhor. É uma arquitetura fundamentalmente diferente.

Como os Doze Agents da Apollo Space Mapeiam para Esta Arquitetura

Todo agent da Apollo Space usa o mesmo loop PRAO e o mesmo sistema de memória em três camadas, mas os detalhes de implementação variam por função.

Agent SDR: Memória episódica pesada (cada interação de outreach registrada), conjunto rico de ferramentas (email, LinkedIn, CRM, calendário), loop de decisão rápido (múltiplas decisões por hora durante horário comercial).

Agent de QA: Memória procedural pesada (procedimentos de teste aprendidos de bugs passados), ferramentas especializadas (automação de browser, testes de API, regressão visual), loop de decisão baseado em eventos (acionado por novos PRs e commits).

Agent de Competitor Watch: Memória semântica pesada (knowledge graph de concorrentes), ferramentas pesadas em informação (web scraping, detecção de mudanças, agregação de dados), loop de decisão lento (roda em ciclos de 6 horas para monitoramento, tempo real para alertas).

Agent de Observabilidade: Memória episódica mínima (métricas são time-series, armazenadas externamente), ferramentas pesadas em análise (correlação de métricas, detecção de anomalias, análise de causa raiz), loop de decisão em tempo real (monitoramento contínuo com thresholds de alerta configuráveis).

Agent de Meeting Digest: Memória episódica moderada (reuniões passadas e action items), ferramentas focadas (transcrição, sumarização, extração de tarefas, integração com calendário), loop baseado em eventos (acionado por conclusão de reunião).

A arquitetura é consistente. A configuração é específica. Esse é o princípio de design que nos permite rodar doze agents sem doze codebases separados, um framework, doze configurações, e a especialização vive na memória e nos conjuntos de ferramentas em vez de no código.

Os 80% Que Não São o Modelo

Aqui está a coisa que ninguém no ciclo de hype de IA quer admitir: o LLM é talvez 20% do que faz um agent funcionar.

Os outros 80% são o sistema de memória (como você armazena, recupera e mantém o conhecimento do agent), a camada de ferramentas (como o agent age no mundo de forma confiável e segura) e o loop de decisão (como percepção flui para raciocínio flui para ação flui para observação). Esses são problemas de engenharia de sistemas, não problemas de machine learning.

Quando um time nos diz que seu agent não está funcionando bem, nove em dez vezes o problema não é o modelo. É que o agent está raciocinando com contexto insuficiente porque a recuperação de memória é ruim. Ou o agent está tomando boas decisões mas não consegue executá-las porque a camada de ferramentas é frágil. Ou o agent fica preso em loops porque o loop de decisão não tem detecção de divergência adequada.

Troque o modelo de GPT-4 para Claude para Gemini, e a performance do agent muda talvez 10-15%. Melhore o sistema de recuperação de memória, e a performance muda 40-60%. Essa é a lacuna entre a narrativa (IA é sobre modelos) e a realidade (agents são sobre sistemas).

Construa o sistema certo, e o modelo é um componente substituível. Construa o sistema errado, e nenhum modelo vai te salvar.