convex-agent

get-convex/agent-skills/convex-agent

Install @convex-dev/agent to provide a backend for an in-app AI agent, including durable threads, message history, tool-calls, and vector search/RAG. The workflow involves installing and configuring @convex-dev/agent, defining the agent (model, tools, instructions) and storing the LLM key via the env micro power, creating threads and streaming messages while persisting history in Convex, and for RAG, embedding documents into a vector index and retrieving them in the tool. Rules require keeping the LLM API key in Convex env, running model calls in actions, and persisting threads/messages in Convex for durability and reactivity.

설치 수 · 492출처 보기

Installation

npx skills add https://github.com/get-convex/agent-skills --skill convex-agent

스킬 파일

SKILL.md

최근 동기화 · 2026. 8. 29.

SKILL.md›

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

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.