Building AI agents with the Convex Agent component including thread management, tool integration, streaming responses, RAG patterns, and workflow orchestration
No setup needed. Let our cloud agents run this skill for you.
Select Provider
Select Model
Claude Sonnet 4.5
$0.20/task
Best for coding tasks
Environment setup included
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:
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
npm install @convex-dev/agent ai openai
// convex/agent.tsimport { 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
// convex/threads.tsimport { mutation, query } from "./_generated/server";import { v } from "convex/values";import { agent } from "./agent";// Create a new conversation threadexport const
Sending Messages and Streaming Responses
// convex/chat.tsimport { action } from "./_generated/server";import { v } from "convex/values";import { agent } from "./agent";import { internal } from "./_generated/api";export
Tool Integration
Define tools that agents can use:
// convex/tools.tsimport { tool } from "@convex-dev/agent";import { v } from "convex/values";import { api } from "./_generated/api";
Agent with Tools
// convex/assistant.tsimport { action } from "./_generated/server";import { v } from "convex/values";import { agent } from "./agent";import { searchKnowledge, createTask, getWeather } from "./tools";export const chat =
RAG (Retrieval Augmented Generation)
// convex/knowledge.tsimport { mutation, query } from "./_generated/server";import { v } from "convex/values";import { agent } from "./agent";// Add document to knowledge baseexport
Workflow Orchestration
// convex/workflows.tsimport { action, internalMutation } from "./_generated/server";import { v } from "convex/values";
Examples
Complete Chat Application Schema
// convex/schema.tsimport { defineSchema, defineTable } from "convex/server";import { v } from "convex/values";export default defineSchema({ threads: defineTable({ userId: v.id("users"
React Chat Component
import { useQuery, useMutation, useAction } from "convex/react";import { api } from "../convex/_generated/api";import { useState, useRef, useEffect } from "react"
Best Practices
Never run npx convex deploy unless explicitly instructed
Never run any git commands unless explicitly instructed
Store conversation history in Convex for persistence
Use streaming for better user experience with long responses
Implement proper error handling for tool failures
Use vector indexes for efficient RAG retrieval
Rate limit agent interactions to control costs
Log tool usage for debugging and analytics
Common Pitfalls
Not persisting threads - Conversations lost on refresh
Blocking on long responses - Use streaming instead
Claude Sonnet 4.5