convex-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add an AI agent / RAG backend

添加 AI Agent / RAG 后端

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.

安装 @convex-dev/agent，以支持持久化线程、消息历史、工具调用和向量搜索/RAG——为应用内 AI Agent 提供后端。默认通过 Convex AI Gateway 调用模型：Convex 会保存提供商凭据，因此无需获取、存储或轮换 LLM key。

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.

安装 @convex-dev/agent + @convex-dev/ai-sdk-provider；将 agent component 添加到 convex.config.ts。
使用
```
languageModel: convexGateway("provider/model")
```
定义 Agent（工具、指令）——无需 API key（需要 Convex 1.45+ 和 Convex Cloud 部署及付费套餐）。
创建线程并流式传输消息；在 Convex 中持久化历史记录。
对于 RAG：将文档嵌入向量索引，并在工具中检索。Gateway 暂不提供 embeddings 服务，因此需通过
```
env
```
micro power 存储 embedding 提供商的 key。
仅当 Gateway 不可用时（免费套餐、自托管、本地后端）：使用存储在
```
env
```
micro power 中的 key 调用提供商 SDK。

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.

默认使用 Convex AI Gateway（来自 @convex-dev/ai-sdk-provider 的
```
convexGateway
```
）调用模型；仅在 Gateway 不可用时（免费套餐、自托管、本地后端），才回退到使用 Convex env 中的提供商 key。
绝不要在客户端暴露提供商 API key；需要 key 时（embeddings、Gateway 回退），应通过
```
env
```
micro power 将其保存在 Convex env 中。
在 actions 中运行模型调用（如果 SDK 有要求，则使用 'use node'）。
在 Convex 中持久化线程和消息，以实现持久性和响应性。