---
id: gh-convex-agent
name: "convex-agent"
url: https://skills.yangsir.net/skill/gh-convex-agent
author: convex
domain: ai-agent-core-development
tags: ["convex", "ai-agent", "rag", "vector-search", "backend"]
install_count: 34900
rating: 4.60 (120 reviews)
github: https://github.com/convex/agent-skills/tree/main/skills/convex-agent
---

# convex-agent

> 该 Skill 为 Convex 应用接入 @convex-dev/agent，快速搭好 AI Agent 与 RAG 后端：定义工具与指令、创建持久线程、流式返回消息，并把历史与向量检索结果存进 Convex。模型调用默认走 Convex AI Gateway，无需自行申请或轮换 LLM 密钥，适合需要在应用内嵌智能问答、文档检索或工具调用能力的团队。

**Stats**: 34,900 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 接入可持久化的 AI Agent 后端

**Before**:

开发者要自己挑模型 SDK、申请并保管 API Key、手写线程与消息存储、拼接流式响应，还要另搭一套向量检索，光把链路打通就要好几天，密钥散落各处也难审计。

**After**:

该 Skill 给出安装、定义 Agent、建线程、流式消息到向量检索的完整步骤，模型凭证由服务端托管，半天内即可跑通可持久化、可响应的 Agent 与 RAG 后端。

| Metric | Before | After | Change |
|---|---|---|---|
| 后端搭建耗时 | 480分钟 | 60分钟 | -88% |
| 需自行保管的 LLM 密钥 | 3个 | 0个 | -100% |
| 消息历史自建数据表 | 4张 | 1张 | -75% |

## Readme

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


---
*Source: https://skills.yangsir.net/skill/gh-convex-agent*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-convex-agent/markdown*