LabscoConnect MCP ↗
get-convex logo✓ Official★ 63

convex-agent

Builds the server side of an AI assistant inside your Convex app: conversation threads, saved message history, tool calls and search over your own documents. Model calls go through Convex's AI Gateway by default, so there is no AI provider key to look after.

by get-convexpart of get-convex/agent-skills

One of 30 skills in the get-convex/agent-skills package — works on its own, and pairs well with its siblings.

WHEN YOUR AGENT SHOULD USE IT

A QUICK BOUNDARY

USE FOR

  • Add a chat assistant that remembers each conversation.
  • Let the assistant call tools you define.
  • Answer questions from your own documents by searching them first.
  • Stream replies to the screen as they are written.

Documents

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

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
  1. Install @convex-dev/agent + @convex-dev/ai-sdk-provider; add the agent component to convex.config.ts.
  2. 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).
  3. Create threads + stream messages; persist history in Convex.
  4. 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.
  5. 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.

Installation

Copy & paste — that's it
npx skills add get-convex/agent-skills --skill "convex-agent" --full-depth

Run this in your project — your agent picks the skill up automatically.

BEFORE IT WILL WORK

2 FOR YOU
  1. 01
    A paid Convex Cloud plan for the keyless AI Gateway

    The keyless AI Gateway needs Convex 1.45 or later on a paid Convex Cloud plan. On the free plan, self-hosted or local, the skill uses your own AI provider key, stored in your Convex settings.

  2. 02
    An embeddings provider key, for document search

    Searching your own documents needs a key from an embeddings provider, because the gateway does not offer embeddings yet.

License

Licensed under Apache-2.0— you can use, modify, and redistribute it under that license's terms.

View the full license file on GitHub →