Skills

Skill 3 of 33

Convex Agent

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

1 minute · 254 words · 3 sections

Install

$ npx skills add get-convex/agent-skills --skill convex-agent

$ npx skills add get-convex/agent-skills

The first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.

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 env micro power.
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.

Colophon for this issue

Colophon

How this issue was made

Source

github.com/get-convex/agent-skills, branch main, last pushed 9 September 2026.

Licence

Apache-2.0 — the text of every skill is reproduced unmodified, frontmatter included, under the upstream licence.

Discovery

33 skills found by walking the repository tree for SKILL.md, not by matching a directory convention. One layout observed: skills/*/SKILL.md.

Issue colours

Resolved from a deterministic hash of the owner name. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.

Heading repairs

1 repair applied to this skill so the document has one h1 and no skipped levels:

Shifted “3 headings” from h1 to h2 so the skill title is the only h1.

Spec compliance

Every skill satisfies the Agent Skills specification’s frontmatter rules.

Images

Images inside a skill come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.

Signal

Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.

Agent surfaces

The whole issue is available as one markdown document at /get-convex/agent-skills.md, and each skill at its own .md URL.

Publication

Set by Skills Docs from the source repository. Body text is Literata at the reader’s chosen size and measure; code is Geist Mono. Nothing on this page was written by us except this paragraph.

Add an AI agent / RAG backend

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 env micro power.

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.

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.