convex-agent

用途 该技能用于向 Convex 应用添加 AI 智能体 / RAG 后端（@convex-dev/agent），为应用内 AI 智能体提供后端支持，涵盖持久化线程、消息历史、工具调用以及向量搜索 / RAG。

主要能力

• 持久化线程与消息历史。
• 工具调用（tool-calls）。
• 向量搜索 / RAG。
• 默认通过 Convex AI Gateway 调用模型：Convex 持有服务商凭证，因此无需获取、存储或轮换 LLM 密钥。

使用方式

1. 安装 @convex-dev/agent 与 @convex-dev/ai-sdk-provider；在 convex.config.ts 中添加 agent 组件。
2. 使用 languageModel: convexGateway("provider/model") 定义智能体（工具、指令），无需 API 密钥（需要 Convex Cloud 部署上的 convex 1.45+ 及付费计划）。
3. 创建线程并流式传输消息；将历史持久化到 Convex。
4. RAG：将文档嵌入向量索引，并在工具中检索。网关暂不提供嵌入服务，因此需通过 env micro power 存储嵌入服务商的密钥。
5. 仅当网关不可用（免费计划、自托管、本地后端）时：改用服务商 SDK 调用，密钥通过 env micro power 存储。

规则与限制

• 模型调用默认使用 Convex AI Gateway（来自 @convex-dev/ai-sdk-provider 的 convexGateway）；仅在网关不可用（免费计划、自托管、本地后端）时回退到 Convex env 中的服务商密钥。
• 绝不在客户端暴露服务商 API 密钥；需要密钥时（嵌入、网关回退），通过 env micro power 保存在 Convex env 中。
• 在 actions 中执行模型调用（若 SDK 需要则使用 'use node'）。
• 为持久性与响应性，将线程 / 消息持久化在 Convex 中。

适用场景 需要为 Convex 应用构建应用内 AI 智能体或 RAG 后端的开发场景。

限制与暂未提供 使用 Convex AI Gateway 需 Convex Cloud 部署上的 convex 1.45+ 及付费计划；网关目前不提供嵌入服务。关于收费、价格、性能效果等资料暂未提供。