Convex Agents
Implement production AI agents on Convex with threads, tools, streaming, and RAG patterns instead of piecing together docs from scratch.
Overview
Convex Agents is an agent skill for the Build phase that teaches how to build AI agents with the Convex Agent component, including threads, tools, streaming, and RAG patterns.
Install
npx skills add https://github.com/waynesutton/convexskills --skill convex-agentsWhat is this skill?
- Convex Agent component patterns: thread management and persistent conversation state
- Tool integration and streaming responses for interactive agent UIs
- RAG-oriented patterns suited to Convex-backed apps
- Official Convex skills packaging with branded skill metadata
- Backend-realtime pairing for solo builders shipping agent features on one stack
Adoption & trust: 1.3k installs on skills.sh; 402 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want persistent, tool-using agents on Convex but lack a single skill that covers threads, streaming, and RAG in one implementation path.
Who is it for?
Solo builders shipping agent features on Convex who need thread + tool + streaming patterns in one place.
Skip if: Pure prompt-only chatbots with no backend, teams not using Convex, or marketers seeking SEO or interview scripts.
When should I use this skill?
Building AI agents with the Convex Agent component including thread management, tool integration, streaming responses, and RAG patterns.
What do I get? / Deliverables
Your agent follows Convex Agent component conventions for thread lifecycle, tool calls, and streamed responses ready to integrate into your app backend.
- Agent thread and tool integration design
- Streaming response pattern
- RAG-oriented Convex agent setup notes
Recommended Skills
Journey fit
Convex Agents is implementation work—wiring agent runtime, persistence, and tools—so it belongs on the Build shelf, not distribution or ops. Agent-tooling subphase is for agent components, tool loops, and streaming; this skill is explicitly the Convex Agent building guide.
How it compares
Convex-focused agent implementation skill—not a generic LangChain tutorial or an MCP server catalog entry.
Common Questions / FAQ
Who is convex-agents for?
It is for developers and solo founders building AI agents on Convex who need structured guidance on the Agent component, tools, and streaming.
When should I use convex-agents?
Use it during Build while designing agent-tooling and backend integrations for a Convex app, before you ship agent features to production.
Is convex-agents safe to install?
Treat it like any third-party skill from waynesutton/convexskills; check the Security Audits panel on this page and review generated code before deploying with network and secrets.
SKILL.md
READMESKILL.md - Convex Agents
interface: icon_small: "./assets/small-logo.svg" icon_large: "./assets/large-logo.png" <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"> <g clip-path="url(#clip0_3_23)"> <g clip-path="url(#clip1_3_23)"> <path d="M10.0643 12.5735C12.3769 12.3166 14.5572 11.0843 15.7577 9.02756C15.1892 14.1148 9.62646 17.3302 5.08583 15.356C4.66743 15.1746 4.30728 14.8728 4.06013 14.4848C3.03973 12.8825 2.7043 10.8437 3.18626 8.99344C4.56327 11.37 7.3632 12.8267 10.0643 12.5735Z" fill="#F3B01C"/> <path d="M3.1018 7.50072C2.16436 9.66714 2.12376 12.2034 3.27303 14.2907C-0.771507 11.2479 -0.72737 4.7362 3.2236 1.72378C3.58904 1.44535 4.02333 1.2801 4.47881 1.25494C6.3519 1.15614 8.25501 1.88006 9.58963 3.22909C6.87799 3.25604 4.23695 4.99308 3.1018 7.50072Z" fill="#8D2676"/> <path d="M10.8974 3.89562C9.52924 1.98794 7.38779 0.68921 5.04156 0.649695C9.57686 -1.40888 15.1555 1.92867 15.7629 6.86314C15.8194 7.32119 15.7452 7.78824 15.5421 8.20138C14.6948 9.92223 13.1236 11.2569 11.2876 11.7508C12.6328 9.25579 12.4668 6.20748 10.8974 3.89562Z" fill="#EE342F"/> </g> </g> <defs> <clipPath id="clip0_3_23"> <rect width="16" height="16" fill="white"/> </clipPath> <clipPath id="clip1_3_23"> <rect width="16" height="16" fill="white"/> </clipPath> </defs> </svg> --- name: convex-agents displayName: Convex Agents description: Building AI agents with the Convex Agent component including thread management, tool integration, streaming responses, RAG patterns, and workflow orchestration version: 1.0.0 author: Convex tags: [convex, agents, ai, llm, tools, rag, workflows] --- # Convex Agents Build persistent, stateful AI agents with Convex including thread management, tool integration, streaming responses, RAG patterns, and workflow orchestration. ## Documentation Sources Before implementing, do not assume; fetch the latest documentation: - Primary: https://docs.convex.dev/ai - Convex Agent Component: https://www.npmjs.com/package/@convex-dev/agent - For broader context: https://docs.convex.dev/llms.txt ## Instructions ### Why Convex for AI Agents - **Persistent State** - Conversation history survives restarts - **Real-time Updates** - Stream responses to clients automatically - **Tool Execution** - Run Convex functions as agent tools - **Durable Workflows** - Long-running agent tasks with reliability - **Built-in RAG** - Vector search for knowledge retrieval ### Setting Up Convex Agent ```bash npm install @convex-dev/agent ai openai ``` ```typescript // convex/agent.ts import { Agent } from "@convex-dev/agent"; import { components } from "./_generated/api"; import { OpenAI } from "openai"; const openai = new OpenAI(); export const agent = new Agent(components.agent, { chat: openai.chat, textEmbedding: openai.embeddings, }); ``` ### Thread Management ```typescript // convex/threads.ts import { mutation, query } from "./_generated/server"; import { v } from "convex/values"; import { agent } from "./agent"; // Create a new conversation thread export const createThread = mutation({ args: { userId: v.id("users"), title: v.optional(v.string()), }, returns: v.id("threads"), handler: async (ctx, args) => { const threadId = await agent.createThread(ctx, { userId: args.userId, metadata: { title: args.title ?? "New Conversation", createdAt: Date.now(), }, }); return threadId; }, }); // List user's threads export const listThreads = query({ args: { userId: v.id("users") }, returns: v.array(v.object({ _id: v.id("threads"), title: v.string(), lastMessageAt: v.optional(v.number()), })), handler: async (ctx, args) => { return await agent.listThreads(ctx, { userId: args.userId, }); }, }); // Get thread messages export const getMessages = query({ args: { threadId: v.id("threads") }, returns: v.array(v.object({ role: v.string(), content: v.string(), createdAt: v.number(), })), handler: async