convex-agents

Build persistent AI agents with Convex threads, tools, streaming, and RAG.

1|Updated Oct 10, 2025
One-click install
npx skills add https://github.com/Rocktown-Labs/rivercitymd --skill convex-agents-rocktown-labs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: convex-agents
Source: https://github.com/Rocktown-Labs/rivercitymd/tree/main/.cursor/skills/convex-agents
Command: npx skills add https://github.com/Rocktown-Labs/rivercitymd --skill convex-agents-rocktown-labs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @convex-dev/agent, ai, openai.

What problem does it solve? Building AI agents that remember conversations, call tools, and stream responses requires stitching together state management, vector search, and real-time infrastructure. This Skill provides ready-to-use patterns for building stateful agents on Convex so conversation history, embeddings, and workflows persist without extra infrastructure. ## Core Features & Use Cases - Thread & Message Management: Create conversation threads, list user threads, and retrieve message history stored in Convex tables. - Tool Integration: Define Convex functions as agent tools (knowledge search, task creation, external API calls) that the LLM can invoke during chat. - RAG & Vector Search: Generate embeddings on document insert and query them with vector indexes for retrieval-augmented generation. - Workflow Orchestration: Run multi-step agent workflows (search, analyze, summarize) with status tracking in the database. - Use Case: Add an AI support assistant to your app that remembers each customer's conversation, searches your knowledge base for answers, and creates follow-up tasks automatically. ## Quick Start Ask the AI to set up a Convex agent with a chat thread, a knowledge search tool, and streaming responses using the @convex-dev/agent component.

Frequently Asked Questions about convex-agents

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I build an AI agent with Convex?▼

Install @convex-dev/agent, ai, and openai, then create an Agent instance with your OpenAI chat and embedding clients. Use agent.createThread for conversations and agent.chat to generate responses with optional tools and streaming.

How do I add tools to a Convex agent?▼

Define tools with the tool() function from @convex-dev/agent, specifying a name, description, parameters validator, and handler. Pass the tools array to agent.chat so the LLM can invoke them during conversation.

Does Convex support RAG with vector search?▼

Yes, Convex supports vector indexes on tables storing embedding arrays. Generate embeddings with agent.embed when inserting documents, then use agent.search to retrieve relevant documents by query similarity.

How do I stream agent responses to a React client?▼

Pass stream: true and an onToken callback to agent.chat, writing each token to the database via a mutation. Convex real-time queries then push updates to subscribed React components automatically.

Why is my agent losing conversation history on refresh?▼

History is lost when threads and messages are not persisted to Convex tables. Store every user message and assistant response via mutations indexed by threadId so queries can reload the full conversation.