Building AI agents with the Convex Agent component including thread management, tool integration, streaming responses, RAG patterns, and workflow orchestration

Convex agents Produces a chat or tool calling agent backed by @convex dev/agent , with thread history stored in Convex and a reactive message list for the UI. The one rule: every LLM call runs inside an action. Mutations save the prompt and schedule the action; they never call a model. When to reach for this Adding a chat assistant with persistent conversation history Letting an LLM call your queries and mutations as tools Streaming a model reply to one or more clients Answering questions over your own documents (RAG) Chaining several LLM steps into a durable job that survives restarts Install and register Run npx convex dev once so components.agent is generated before defining an agent. Define an agent name tags each saved message with the agent that wrote it. Everything except name can be overridden per call. Create a thread and generate a reply Save the user prompt in a mutation, then schedule an internal action that generates the reply. Clients subscribed to the thread see the new message without the action returning anything. Thread ids are strings, not v.id(...) , since the table lives inside the component. List messages for the UI listUIMessages merges tool calls and the assistant text that follows them into one UIMessage , which keeps rendering simple. One tool Tools are defined with createTool and get a ctx that includes runQuery , runMutation , userId , and threadId . Annotate the handler return type to avoid circular type errors. Pass it to the agent with tools: { searchOrders } in the constructor or at the call site. For tool error handling, runtime tools with closures, and delta streaming to the client, open [references/tools and streaming.md](references/tools and streaming.md). Retrieval and multi step jobs For embedding documents, searching them with @convex dev/rag or a hand rolled vector index, injecting results into the prompt, and running several LLM steps as a durable @convex dev/workflow job, open [references/rag and workflows.md](references/rag and workflows.md). Common mistakes Mistake Why it breaks Do instead Calling generateText in a mutation Mutations cannot make network calls and must be deterministic Save the prompt with saveMessage , schedule an internalAction v.id("threads") for thread ids The threads table lives in the component, so ids are strings outside it Use v.string() Skipping npx convex dev after app.use(agent) components.agent is not generated, so types fail Run dev once before writing agent code Returning the reply text from the action to the client Loses the reply if the client disconnects, no reactivity Let clients read listUIMessages ; the saved message shows up on its own Tools without .describe() on args The model guesses what each field means and calls tools badly Describe every zod field Tool handler with no return type annotation TypeScript circularity errors from ctx.runQuery Add : Promise<... to the handler Exposing the message query with no auth check Any client can read any thread Call an authorizeThreadAccess helper first stopWhen left at the default with tools defined The model calls a tool and stops without a text reply Set stopWhen: stepCountIs(n) with n 1 Checklist [ ] app.use(agent) in convex.config.ts and npx convex dev has run [ ] Provider key stored with npx convex env set , never in client code [ ] Agent has a name , languageModel , and instructions [ ] Prompts saved in a mutation, replies generated in an internalAction with promptMessageId [ ] Thread and message ids typed as v.string() [ ] Message list query checks thread ownership before calling listUIMessages [ ] Every tool arg has a zod .describe() and the handler has a return type [ ] stopWhen: stepCountIs(n) set when tools are in play [ ] Client uses useUIMessages rather than reading action return values Docs https://docs.convex.dev/llms.txt https://docs.convex.dev/agents https://docs.convex.dev/agents/agent usage https://docs.convex.dev/agents/tools https://www.convex.dev/components/agent

convex-agents