convex-agents-fundamentals_skill

Overview

This skill sets up and configures Convex agents for chat-based AI interactions, providing the foundational patterns for creating agent instances, threads, and basic LLM responses. It focuses on initializing agents, managing per-user conversation threads, and producing text or structured outputs that are stored and reused. Use it as the baseline for any Convex agent implementation.

How this skill works

Install the agent component into your Convex app and instantiate Agent objects with a chat model and optional default instructions. Create per-user threads to isolate conversation history, then call generation methods on those threads to produce text or structured JSON. Generated messages are stored automatically and recent message history is included in each LLM call, while actions are used for async LLM calls and mutations for transactional writes.

When to use it

• Bootstrapping your first Convex agent in a project
• Creating or continuing per-user conversation threads
• Generating text replies or structured JSON from a chat model
• Configuring agent defaults like system prompt and model selection
• Building simple chat interfaces that rely on message history

Best practices

• Create one thread per user or conversation to ensure thread isolation
• Include userId when creating threads to keep per-user organization
• Use actions for any LLM calls to keep async behavior safe in Convex
• Provide explicit return types on server code to maintain type safety
• Rely on automatic message storage and recent history rather than re-sending full context

Example use cases

• Initialize a My Assistant agent with a specific chat model and default instructions
• Create a new conversation thread when a user starts a chat and return the threadId
• Continue an existing thread and call thread.generateText({ prompt }) to get a reply
• Produce structured JSON responses (e.g., form data) from the model and store them in the thread
• Build a chat UI that reads thread history and calls thread.generateText for new messages