Convex gets official agent component with built-in memory and RAG

Anyone already building full-stack products on Convex knows the pattern: automatic reactivity on the client, typed server-side functions, and a database that syncs itself. What was missing, for those who wanted to put an AI agent in this stack, was combining conversation history, long-term memory, and context retrieval without plugging in a separate vector DB (Pinecone, Weaviate, pgvector) and stitching it all together by hand. That's exactly the gap the Agent Component (@convex-dev/agent) fills, according to the official Convex documentation.

The core idea, described in the docs themselves, is to separate long-running agentic flows from the UI without losing reactivity. Message history with the LLM is persisted by default and live-updates across all connected clients. Instead of configuring this through config files, you compose it with the rest of the backend using code.

What the component solves

The Agent Component organizes three things that normally live in separate services:

• Threads: persist messages and can be shared by multiple users and agents (including human agents, in support handoff scenarios).
• Automatic context: on every call to the LLM, the component injects conversation context using hybrid vector/text search across messages. In other words, embedding and semantic retrieval of the history are already built in.
• Tools: the agent ties model, prompt, and tools together in a single object, and can generate both text and structured objects, with streaming.

The point the editor highlighted is worth reinforcing: for products already running on Convex, this eliminates the separate vector DB for the case of RAG over the conversation history itself. One less service to provision, pay for, and keep in sync.

What this looks like in practice

The documentation's example defines a support agent and uses it from inside a regular Convex action. The code below is what the docs present:

import { Agent } from "@convex-dev/agents";
import { openai } from "@ai-sdk/openai";
import { components } from "./_generated/api";
import { action } from "./_generated/server";

// Define an agent
const supportAgent = new Agent(components.agent, {
  name: "Support Agent",
  chat: openai.chat("gpt-4o-mini"),
  instructions: "You are a helpful assistant.",
  tools: { accountLookup, fileTicket, sendEmail },
});

// Use the agent from inside a regular action:
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 };
  },
});

The important detail is resuming a conversation. To continue where it left off, with the same agent or a different one, all you need is the threadId, and the previous history is automatically included in the call:

export const continueThread = action({
  args: { prompt: v.string(), threadId: v.string() },
  handler: async (ctx, { prompt, threadId }) => {
    // This already includes the thread's message history automatically.
    const { thread } = await anotherAgent.continueThread(ctx, { threadId });
    const result = await thread.generateText({ prompt });
    return result.text;
  },
});

Notice that the agent lives inside a Convex action, side by side with the rest of the business logic. That's the component's selling point: you write agentic code with the same abstractions you already use for query, mutation, and action, instead of pushing that part off to an external orchestration service. chat is plugged in via the AI SDK (@ai-sdk/openai), so switching model providers is just a matter of swapping the adapter.

Beyond the basics: workflows, RAG, and files

The docs list features that go beyond simple chat:

• Workflows: multi-step operations that span agents and users in a durable, reliable way, for flows that don't fit in a single call.
• Dedicated RAG: besides searching the history, there's the RAG Component for augmenting the prompt with your own knowledge base, either ahead of time or as a tool call during execution. This is where the distinction that confuses many people comes in: the built-in hybrid search covers the conversation history; for RAG over your own documents, it's the RAG Component that does the work.
• Files: can be included in the chat history with automatic saving to Convex's file storage.

Observability and cost control

An agent in production without visibility is technical debt waiting to come due. The component brings three fronts that the docs call debugging and tracking:

| Feature | What it's for | |---|---| | Agent playground | Inspecting metadata and iterating on prompts and context settings | | Usage tracking | Measuring consumption to bill per user or team | | Rate limiting | Throttling interaction frequency to avoid hitting the LLM provider's limit |

Usage tracking is what makes it feasible to charge the end user for AI usage, a common scenario in Brazilian SaaS products that embed assistants. Rate limiting protects against the nightmare of runaway costs when a user (or a bug) fires off calls in a loop.

What changes for those building in Brazil

For smaller teams, which make up a good share of those adopting Convex here, the concrete gain is reducing the infrastructure surface. A support agent with conversation memory and semantic search would normally require: a relational database, a vector DB, a queue for long-running flows, and a sync layer with the front end. The component concentrates all of that in the same reactive backend.

The honest trade-off: by adopting the Agent Component, you couple more deeply to Convex. If the product roadmap involves leaving the BaaS later, this agentic layer becomes one more migration point, and it's not trivial to replicate the built-in hybrid search on another stack. It's also worth not confusing convenience with a silver bullet: for large knowledge bases and fine-grained ranking requirements, a dedicated vector DB with full control over embeddings and filters can still make more sense than the built-in search.

The practical recommendation for those already on Convex who want to experiment: start with the "Build your first Agent" tutorial in the docs themselves, measure cost with usage tracking from day one, and only then decide whether the RAG Component covers the use case or whether an external vector DB is really necessary. The official starting point is at docs.convex.dev/agents.