convex-agent
get-convex/agent-skills
Add durable AI agent and RAG backend to Convex with built-in message history, tool calls, and vector search.
What is convex-agent?
Install @convex-dev/agent to add an AI agent backend with durable threads, message history, tool-calling, and vector search/RAG capabilities. Use the Convex AI Gateway by default (no API key management needed on paid plans), or fall back to provider credentials for self-hosted or free deployments.
- Create and manage durable agent threads with persistent message history
- Execute tool calls and define custom agent instructions
- Perform vector search and RAG with embedded documents
- Call LLM models through Convex AI Gateway without managing provider keys
- Fall back to provider SDKs with credentials stored securely in Convex env
- Stream messages and maintain reactive state in Convex database
How to install convex-agent
npx skills add https://github.com/get-convex/agent-skills --skill convex-agent- Convex 1.45+ (for gateway support on paid plans)
- @convex-dev/agent and @convex-dev/ai-sdk-provider packages
- Convex Cloud deployment (paid plan for gateway, or self-hosted/free with provider key)
- Vector embedding provider key (if using RAG; stored via env micro power)
How to use convex-agent
- 1.Run `npx skills add https://github.com/get-convex/agent-skills --skill convex-agent`
- 2.Install @convex-dev/agent and @convex-dev/ai-sdk-provider packages
- 3.Add the agent component to convex.config.ts
- 4.Define your agent with tools and instructions using `convexGateway("provider/model")`
- 5.Create threads and stream messages; persist history in Convex database
- 6.For RAG: embed documents into a vector index and retrieve via agent tools
- 7.Store any required provider keys (embeddings, fallback) in Convex env using the env micro power
Use cases
- Build in-app AI assistants with persistent conversation history
- Implement retrieval-augmented generation (RAG) over custom documents
- Create multi-turn agent workflows with tool integration
- Deploy AI agents without managing LLM API keys client-side
- Add semantic search capabilities via vector embeddings
- Convex backend developers
- Full-stack engineers building AI-powered applications
- Teams deploying agents on Convex Cloud paid plans
- Developers implementing RAG systems
convex-agent FAQ
No, by default the Convex AI Gateway handles credentials on paid plans. Only store provider keys in Convex env if using embeddings or falling back on free/self-hosted deployments.
Yes, but you must fall back to calling provider SDKs directly with credentials stored in Convex env, since the gateway is only available on paid plans.
Embed your documents into a vector index, then retrieve relevant documents in an agent tool. Store the embedding provider key in Convex env via the env micro power.
Always run model calls in Convex actions (use 'use node' if the SDK requires it) to keep credentials server-side and ensure durability.
Yes, threads and messages are persisted in the Convex database for durability and reactivity.
Full instructions (SKILL.md)
Source of truth, from get-convex/agent-skills.
name: convex-agent description: "Add an AI agent / RAG backend (@convex-dev/agent) to the Convex app."
<!-- GENERATED from convex-agents content/capabilities/agent.json — do not edit by hand. -->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
envmicro power. - Only if the gateway is unavailable (free plan, self-hosted, local backend): call the provider SDK with a key stored via the
envmicro power.
Rules
- Default to the Convex AI Gateway (
convexGatewayfrom @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
envmicro power. - Run model calls in actions ('use node' if the SDK needs it).
- Persist threads/messages in Convex for durability + reactivity.
Related skills
More from get-convex/agent-skills and the wider catalog.
convex-auth
Add passkey/OAuth authentication to Convex apps with proper auth.config.ts wiring.
convex-authz
Audit and harden Convex app authorization: detect identity spoofing, missing ownership checks, PII leaks, and unsafe parent writes.
convex-backup
Set up Convex backups and prove recovery works with automated restore drills.
convex-billing
Add Stripe billing and subscription management to Convex apps with checkout, webhooks, and server-side gating.
convex-cost
Preview Convex spend by ranking functions on bytes-read × call-volume, project cost curves, and name the cheapest fix.
convex-create-component
Build reusable Convex components with isolated tables and app-facing APIs.