convex-agents
installsforks
How to install convex-agents?
waynesutton/convexskills/convex-agents
$npx -y skills add waynesutton/convexskills --skill convex-agentsBuilding AI agents with the Convex Agent component including thread management, tool integration, streaming responses, RAG patterns, and workflow orchestration
SKILL.md
| 1 | # Convex Agents |
| 2 | |
| 3 | Build persistent, stateful AI agents with Convex including thread management, tool integration, streaming responses, RAG patterns, and workflow orchestration. |
| 4 | |
| 5 | ## Documentation Sources |
| 6 | |
| 7 | Before implementing, do not assume; fetch the latest documentation: |
| 8 | |
| 9 | - Primary: https://docs.convex.dev/ai |
| 10 | - Convex Agent Component: https://www.npmjs.com/package/@convex-dev/agent |
| 11 | - For broader context: https://docs.convex.dev/llms.txt |
| 12 | |
| 13 | ## Instructions |
| 14 | |
| 15 | ### Why Convex for AI Agents |
| 16 | |
| 17 | - **Persistent State** - Conversation history survives restarts |
| 18 | - **Real-time Updates** - Stream responses to clients automatically |
| 19 | - **Tool Execution** - Run Convex functions as agent tools |
| 20 | - **Durable Workflows** - Long-running agent tasks with reliability |
| 21 | - **Built-in RAG** - Vector search for knowledge retrieval |
| 22 | |
| 23 | ### Setting Up Convex Agent |
| 24 | |
| 25 | ```bash |
| 26 | npm install @convex-dev/agent ai openai |
| 27 | ``` |
| 28 | |
| 29 | ```typescript |
| 30 | // convex/agent.ts |
| 31 | import { Agent } from "@convex-dev/agent"; |
| 32 | import { components } from "./_generated/api"; |
| 33 | import { OpenAI } from "openai"; |
| 34 | |
| 35 | const openai = new OpenAI(); |
| 36 | |
| 37 | export const agent = new Agent(components.agent, { |
| 38 | chat: openai.chat, |
| 39 | textEmbedding: openai.embeddings, |
| 40 | }); |
| 41 | ``` |
| 42 | |
| 43 | ### Thread Management |
| 44 | |
| 45 | ```typescript |
| 46 | // convex/threads.ts |
| 47 | import { mutation, query } from "./_generated/server"; |
| 48 | import { v } from "convex/values"; |
| 49 | import { agent } from "./agent"; |
| 50 | |
| 51 | // Create a new conversation thread |
| 52 | export const createThread = mutation({ |
| 53 | args: { |
| 54 | userId: v.id("users"), |
| 55 | title: v.optional(v.string()), |
| 56 | }, |
| 57 | returns: v.id("threads"), |
| 58 | handler: async (ctx, args) => { |
| 59 | const threadId = await agent.createThread(ctx, { |
| 60 | userId: args.userId, |
| 61 | metadata: { |
| 62 | title: args.title ?? "New Conversation", |
| 63 | createdAt: Date.now(), |
| 64 | }, |
| 65 | }); |
| 66 | return threadId; |
| 67 | }, |
| 68 | }); |
| 69 | |
| 70 | // List user's threads |
| 71 | export const listThreads = query({ |
| 72 | args: { userId: v.id("users") }, |
| 73 | returns: v.array(v.object({ |
| 74 | _id: v.id("threads"), |
| 75 | title: v.string(), |
| 76 | lastMessageAt: v.optional(v.number()), |
| 77 | })), |
| 78 | handler: async (ctx, args) => { |
| 79 | return await agent.listThreads(ctx, { |
| 80 | userId: args.userId, |
| 81 | }); |
| 82 | }, |
| 83 | }); |
| 84 | |
| 85 | // Get thread messages |
| 86 | export const getMessages = query({ |
| 87 | args: { threadId: v.id("threads") }, |
| 88 | returns: v.array(v.object({ |
| 89 | role: v.string(), |
| 90 | content: v.string(), |
| 91 | createdAt: v.number(), |
| 92 | })), |
| 93 | handler: async (ctx, args) => { |
| 94 | return await agent.getMessages(ctx, { |
| 95 | threadId: args.threadId, |
| 96 | }); |
| 97 | }, |
| 98 | }); |
| 99 | ``` |
| 100 | |
| 101 | ### Sending Messages and Streaming Responses |
| 102 | |
| 103 | ```typescript |
| 104 | // convex/chat.ts |
| 105 | import { action } from "./_generated/server"; |
| 106 | import { v } from "convex/values"; |
| 107 | import { agent } from "./agent"; |
| 108 | import { internal } from "./_generated/api"; |
| 109 | |
| 110 | export const sendMessage = action({ |
| 111 | args: { |
| 112 | threadId: v.id("threads"), |
| 113 | message: v.string(), |
| 114 | }, |
| 115 | returns: v.null(), |
| 116 | handler: async (ctx, args) => { |
| 117 | // Add user message to thread |
| 118 | await ctx.runMutation(internal.chat.addUserMessage, { |
| 119 | threadId: args.threadId, |
| 120 | content: args.message, |
| 121 | }); |
| 122 | |
| 123 | // Generate AI response with streaming |
| 124 | const response = await agent.chat(ctx, { |
| 125 | threadId: args.threadId, |
| 126 | messages: [{ role: "user", content: args.message }], |
| 127 | stream: true, |
| 128 | onToken: async (token) => { |
| 129 | // Stream tokens to client via mutation |
| 130 | await ctx.runMutation(internal.chat.appendToken, { |
| 131 | threadId: args.threadId, |
| 132 | token, |
| 133 | }); |
| 134 | }, |
| 135 | }); |
| 136 | |
| 137 | // Save complete response |
| 138 | await ctx.runMutation(internal.chat.saveResponse, { |
| 139 | threadId: args.threadId, |
| 140 | content: response.content, |
| 141 | }); |
| 142 | |
| 143 | return null; |
| 144 | }, |
| 145 | }); |
| 146 | ``` |
| 147 | |
| 148 | ### Tool Integration |
| 149 | |
| 150 | Define tools that agents can use: |
| 151 | |
| 152 | ```typescript |
| 153 | // convex/tools.ts |
| 154 | import { tool } from "@convex-dev/agent"; |
| 155 | import { v } from "convex/values"; |
| 156 | import { api } from "./_generated/api"; |
| 157 | |
| 158 | // Tool to search knowledge base |
| 159 | export const searchKnowledge = tool({ |
| 160 | name: "search_knowledge", |
| 161 | description: "Search the knowledge base for relevant information", |
| 162 | parameters: v.object({ |
| 163 | query: v.string(), |
| 164 | limit: v.optional(v.number()), |
| 165 | }), |
| 166 | handler: async (ctx, args) => { |
| 167 | const results = await ctx.runQuery(api.knowledge.search, { |
| 168 | query: args.query, |
| 169 | limit: args.limit ?? 5, |
| 170 | }); |
| 171 | return results; |
| 172 | }, |
| 173 | }); |
| 174 | |
| 175 | // Tool to create a task |
| 176 | export const createTask = tool({ |
| 177 | name: "create_task", |
| 178 | description: "Create a new task for the user", |
| 179 | parameters: v.object({ |
| 180 | title: v.string(), |
| 181 | description: v.optional(v.string()), |
| 182 | dueDate: v.optional(v.string()), |
| 183 | }), |
| 184 | handler: async (ctx, args) => { |
| 185 | const taskId = await ctx.runMutation(api.tasks.create, { |
| 186 | t |
People who liked this also viewed
6 picksType
- azure-storageAzure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier,SkillsJul 2026
- supabase-postgres-best-practicesPostgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.SkillsJul 2026
- supabaseUse when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, SkillsJul 2026
- convex-quickstartCreates or adds Convex to an app. Use for new Convex projects, npm create convex@latest, frontend setup, env vars, or the first npx convex dev run.SkillsJul 2026
- convex-performance-auditAudits Convex performance for reads, subscriptions, write contention, and function limits. Use for slow features, insights findings, OCC conflicts, or read amplification.SkillsJul 2026
- convex-setup-authSets up Convex auth, identity mapping, and access control. Use for login, auth providers, users tables, protected functions, or roles in a Convex app.SkillsJul 2026
