mcpField
C
convex-agent

convex-agent

github.com/growthx-clubAgent workflows0171 installsUpdated 5w ago
Repository

About convex-agent

convex-agent guides developers in using @convex-dev/agent to build an AI agent backend in a Convex app, with durable conversations, tool calls, and vector retrieval. It covers model calls through Convex AI Gateway and RAG setup.

Key features

  1. 01Persist threads and message history
  2. 02Define agent tools and instructions
  3. 03Call models through Convex AI Gateway
  4. 04Build vector indexes and retrieve documents
  5. 05Store keys securely in Convex environment

Use cases

  1. 01Add durable AI conversations to an app
  2. 02Let an agent invoke app-defined tools
  3. 03Generate answers from retrieved documents

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/growthx-club/build-sprint-skills --skill convex-agent

After installing, type/convex-agentin Claude Code to confirm it loaded.

Bundled filesUPSTREAM-LICENSEUPSTREAM-THIRD_PARTY_NOTICES.md

Details

From the project README

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.

Comments

Markdown supported