Convex Agent Component: como funciona a memória e o RAG nativos para agentes de IA

O que o Agent Component resolve

Quem monta um agente de IA↳Agentes de IA42 conteúdosOpera passa a integrar ChatGPT, Claude e outros agentes de IADev (Back & Front) · mar 2026Operações mais inteligentes, decisões mais rápidas: o impacto da IA agêntica na rotina de TIAI · abr 2026Adobe aposta em orquestração de agentes de IA: o que muda para devsDev (Back & Front) · abr 2026Ver tudo em AI → do zero costuma acabar com uma stack fragmentada: um banco relacional para o app, um vector DB (Pinecone, Weaviate, pgvector) para memória semântica, uma fila ou worker para orquestrar chamadas de LLM e algum jeito manual de persistir histórico de conversa. O Agent Component, documentado no Convex Developer Hub, tenta eliminar essa fragmentação empacotando threads, memória e busca semântica dentro do próprio Convex, usando o sistema de Components (algo como plugins de backend↳Back-end49 conteúdosIntegração front-end com backend: 7 decisões que evitam caos entre APIs, BFF e GraphQLDev (Back & Front) · abr 2026Como criar uma FAKE API REST para testes — JSONPlaceholderDev (Back & Front) · set 2025Construindo um aplicativo de bate-papo de IA simples com Spring AI e AngularDev (Back & Front) · jul 2025Ver tudo em Dev (Back & Front) → com banco e funções próprios) que o Convex já oferece para outras integrações.

A ideia central, descrita pelo próprio time do Convex no post que motivou o componente ("AI Agents with Built-in Memory"), é que o histórico de mensagens com um LLM deveria se comportar como qualquer outro dado reativo do Convex: persistido por padrão, atualizado em tempo real em todos os clientes conectados, e componível com o resto da lógica de negócio via código, não configuração.

Threads como unidade central

No modelo do Agent Component, tudo gira em torno de threads. Uma thread guarda o histórico de mensagens e pode ser compartilhada por múltiplos usuários e múltiplos agentes, incluindo agentes humanos (um atendente que assume a conversa de um bot, por exemplo). Isso já é uma diferença de abordagem em relação a bibliotecas de agente que tratam a conversa como estado efêmero em memória do processo: aqui a thread é uma entidade persistida no banco do Convex, então dá para consultar, listar e retomar de qualquer lugar da aplicação.

O exemplo da documentação mostra a criação de um agente e de uma thread:

import { Agent } from "@convex-dev/agent";
import { convexGateway } from "@convex-dev/ai-sdk-provider";

const supportAgent = new Agent(components.agent, {
  name: "Support Agent",
  languageModel: convexGateway("openai/gpt-5-mini"),
  instructions: "You are a helpful assistant.",
});

export const createThread = action({
  args: { prompt: v.string() },
  handler: async (ctx, { prompt }) => {
    const { threadId, thread } = await supportAgent.createThread(ctx);
    const result = await thread.generateText({ prompt });
    return { threadId, text: result.text };
  },
});

O detalhe que vale notar: languageModel recebe um provider do AI SDK (aqui usando o Convex AI Gateway com openai/gpt-5-mini como exemplo), o que significa que o Agent Component não trava o desenvolvedor num único fornecedor de modelo, é possível trocar o provider sem reescrever a lógica de threads.

Para continuar uma conversa depois, basta chamar continueThread passando o threadId. O componente já injeta o histórico anterior no contexto da chamada:

export const continueThread = action({
  args: { prompt: v.string(), threadId: v.string() },
  handler: async (ctx, { prompt, threadId }) => {
    const { thread } = await supportAgent.continueThread(ctx, { threadId });
    const result = await thread.generateText({ prompt });
    return result.text;
  },
});

Onde entra a memória e a busca híbrida

A parte que justifica dispensar um vector DB separado, ao menos para o histórico de conversa, é a busca híbrida vetor/texto embutida nas mensagens da thread. Segundo a documentação, o contexto da conversa é automaticamente incluído em cada chamada ao LLM, combinando busca vetorial (semântica) com busca textual sobre as mensagens já trocadas. Na prática, isso resolve o problema clássico de janela de contexto: em vez de mandar toda a conversa (o que fica caro e eventualmente excede o limite de tokens) ou truncar ingenuamente pelas últimas N mensagens (o que perde contexto relevante mais antigo), o Agent Component pode recuperar os trechos mais pertinentes semanticamente, sem código extra de indexação.

Aqui é importante separar dois níveis de RAG que a documentação do Convex trata como coisas distintas, e essa distinção é o ponto que mais gera confusão:

• Memória de conversa: busca híbrida sobre as próprias mensagens da thread, embutida no Agent Component sem configuração adicional.
• RAG sobre uma base de conhecimento externa (documentos, PDFs, base de FAQ): para isso, o Convex direciona para um componente separado, o RAG Component, que pode ser usado tanto para aumentar o prompt de antemão quanto como uma tool call que o agente decide acionar durante a conversa.

Ou seja, "RAG nativo" no Agent Component cobre bem a memória conversacional, mas RAG documental ainda exige acoplar outro componente Convex, o RAG Component, o que reduz mas não zera a peça extra de infraestrutura. A vantagem é que as duas peças rodam dentro do mesmo backend Convex, com o mesmo sistema de banco reativo, em vez de precisar integrar um serviço de terceiros com sua própria conta, SDK e latência de rede.

O que vem junto: workflows, playground, billing

O Agent Component não é só threads e memória, ele traz um conjunto de peças pensadas para quem vai colocar isso em produção:

• Workflows: para operações de múltiplos passos que atravessam vários agentes e usuários, com garantia de execução durável (se o processo cair no meio, ele retoma do ponto certo).
• Arquivos no histórico: mensagens podem incluir arquivos, com salvamento automático no file storage do Convex, sem o desenvolvedor gerenciar upload e referência manualmente.
• Agent Playground: uma interface para inspecionar metadados de cada chamada e iterar em prompts e configurações de contexto sem precisar reimplantar código a cada ajuste.
• Usage tracking e rate limiting: contadores de uso por usuário/time (para cobrança) e controle de taxa de chamadas, para não estourar o limite do provedor de LLM.

Esse pacote é o argumento de venda do componente: em vez de integrar cinco bibliotecas diferentes para cada uma dessas funções, tudo já conversa com o mesmo banco reativo do Convex.

Quando vale a pena e quando não vale

O caminho natural para testar isso seria partir de um projeto já rodando em Convex e adicionar o pacote @convex-dev/agent para um caso simples de suporte, threads por usuário, sem tocar em RAG documental ainda, e só depois plugar o RAG Component para uma base de FAQ. Isso valida a memória conversacional antes de somar a complexidade da busca sobre documentos externos.

Mas há situações em que essa escolha custa mais do que ajuda. Se a aplicação já roda em outro backend (Postgres↳PostgreSQL11 conteúdosPostgreSQL via SSL com GolangData · abr 20195 itens legais sobre data types do PostgreSQLData · mar 20195 serviços gratuitos na cloud para bancos de dados PostgresData · fev 2025Ver tudo em Data →, Django, uma API em Python) e a ideia é só "colar" um agente, importar o Convex inteiro como banco e camada de funções é uma decisão de infraestrutura bem maior do que adicionar uma biblioteca cliente de LangChain ou do AI SDK puro apontando para um vector DB isolado. O Agent Component pressupõe que as funções do agente (as actions) vivam dentro do modelo de funções do Convex, em TypeScript. Também vale considerar o modelo de custo: busca vetorial e armazenamento de mensagens em escala rodam sobre a precificação do Convex por uso, então times com volume alto de conversas devem simular esse custo antes de assumir que sai mais barato do que uma stack própria com vector DB dedicado, ponto que a documentação não detalha e que cabe a cada equipe medir no próprio caso.

Para times que já usam Convex como BaaS principal e querem adicionar agentes sem multiplicar dependências, o componente resolve a parte mais chata (persistência de thread, contexto automático, busca híbrida) com pouco código, como mostra o exemplo de createThread/continueThread na própria documentação. Para quem não usa Convex, o ganho não compensa a migração só por isso.

Fonte: Convex Docs — Agent Component