AutoGineer
Generated banner for Convex Agent
Generated logo for Convex Agent

Convex Agent

ConvexOfficialPublished by Convex

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • No issues found
Download ZIP

From the author

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

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to adding AI agent functionality, including durable threads, message history, and tool-calling, to a Convex application. It leverages the @convex-dev/agent library and the Convex AI Gateway to simplify LLM integration by managing credentials server-side. The workflow covers setup, agent definition, message persistence, and RAG implementation, ensuring secure handling of API keys and efficient use of Convex's backend infrastructure.

What it does

  • Installs and configures the @convex-dev/agent and @convex-dev/ai-sdk-provider components.
  • Enables model calls through the Convex AI Gateway to avoid manual API key management.
  • Provides patterns for persisting message history and thread state within Convex.
  • Supports RAG implementation by integrating vector search and retrieval tools.
  • Defines best practices for secure environment variable usage for embedding providers.

When to use it

  • When building an in-app AI agent that requires durable conversation state.
  • When you want to integrate LLM capabilities into a Convex project without managing provider keys directly.
  • When implementing RAG features that require vector storage and retrieval within a Convex backend.
  • When you need a reactive, persistent message history for AI interactions.

Advantages

  • Simplifies credential management by using the Convex AI Gateway.
  • Ensures durable and reactive state management for AI threads.
  • Promotes secure development practices by keeping API keys out of client-side code.
  • Provides a unified workflow for both standard LLM interactions and RAG-based tasks.

Usage examples

“How do I set up an AI agent in my Convex app?”
The agent guides you through installing the necessary packages, configuring the agent component in your config file, and defining your model using the convexGateway provider.
“How can I implement RAG with the Convex agent?”
The agent explains how to embed documents into a vector index and retrieve them within your agent tools, while securely storing embedding provider keys in the Convex environment.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/convex/convex-agent/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip convex-agent.zip -d .agents/skills

Documentation by Convex

<!-- 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

  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.

Files

SKILL.md

<!-- 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

  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.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an API key, Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Convex
Publisher
Convex (Official)
Source
convex/agent-skills · skills/convex-agent · commit f60629d
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Convex or Convex.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download convex-agent.zip