Convex Agent

by get-convex2cfe645c87f9No license63 starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 6 days ago

Add an AI agent / RAG backend (@convex-dev/agent) to the Convex app.

Instructions onlyAI & Agents

AI-generated overview

Adds a Convex AI agent and RAG backend using @convex-dev/agent, with durable threads and vector search.

What it does: This skill guides adding an AI agent and RAG backend to a Convex app by installing @convex-dev/agent and @convex-dev/ai-sdk-provider and registering the agent component in convex.config.ts. It covers defining an agent with tools and instructions, creating threads and streaming messages with history persisted in Convex, and embedding documents into a vector index for retrieval. Model calls default to the Convex AI Gateway, with a provider key stored in Convex env as a fallback.
When to use it: Use it when a Convex application needs an in-app AI agent with durable conversation threads, tool calls, or retrieval-augmented generation. It fits projects on Convex Cloud that want model calls without managing an LLM key.
Requirements: Convex 1.45+ on a Convex Cloud deployment on a paid plan for the AI Gateway; the @convex-dev/agent and @convex-dev/ai-sdk-provider packages; an embedding provider key stored in Convex env for RAG; and a provider key in Convex env if the gateway is unavailable. Instructions only, no scripts.

Add an AI agent / RAG backend

Install @convex-dev/agent for durable threads, message history, tool-calls, and vector search/RAG — the backend for an in-app AI agent. Call models through the Convex AI Gateway by default: Convex holds the provider credentials, so there is no LLM key to obtain, store, or rotate.

Workflow

Install @convex-dev/agent + @convex-dev/ai-sdk-provider; add the agent component to convex.config.ts.
Define the agent (tools, instructions) with languageModel: convexGateway("provider/model") — no API key needed (needs convex 1.45+ on a Convex Cloud deployment, paid plan).
Create threads + stream messages; persist history in Convex.
For RAG: embed docs into a vector index and retrieve in the tool. The gateway does not serve embeddings yet, so store the embedding provider's key via the env micro power.
Only if the gateway is unavailable (free plan, self-hosted, local backend): call the provider SDK with a key stored via the env micro power.

Rules

Default to the Convex AI Gateway (convexGateway from @convex-dev/ai-sdk-provider) for model calls; fall back to a provider key in Convex env only where the gateway is unavailable (free plan, self-hosted, local backend).
Never expose a provider API key client-side; when one is needed (embeddings, gateway fallback), keep it in Convex env via the env micro power.
Run model calls in actions ('use node' if the SDK needs it).
Persist threads/messages in Convex for durability + reactivity.

Source and attribution

Source:get-convex/agent-skillsinskills/convex-agentat commit2cfe645

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Convex Agent

Add an AI agent / RAG backend

Workflow

Rules

Source and attribution

More from get-convex/agent-skills

Convex Verify

Convex Test

Convex Suggest

Convex Sentinel

Convex Self Heal

Convex Seed

More in AI & Agents

Skill Development

Plugin Structure

Command Development

Claude Md Improver

Google Cloud Solution Agentic Ai Data Science Workflow

Google Cloud Solution Agentic Ai Borderless Data Lakehouse