agent

用途 该技能用于在 Convex 后端上添加 AI 智能体、聊天机器人或 RAG（检索增强生成）后端，基于 @convex-dev/agent 实现持久化的会话线程、消息历史、工具调用以及向量搜索/检索。

主要能力

• 持久化线程与消息：在 Convex 中保存会话线程与消息记录，兼顾持久性与响应式更新。
• 工具调用：定义智能体的工具与指令，支持在对话过程中调用工具。
• 向量检索/RAG：将文档嵌入写入向量索引，并在工具中执行检索。
• 默认模型调用通道：通过 Convex AI Gateway（来自 @convex-dev/ai-sdk-provider 的 convexGateway）调用模型，Convex 持有服务商凭据，无需获取、保存或轮换 LLM 密钥。

使用方式

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

规则约束

• 模型调用默认使用 Convex AI Gateway；仅在网关不可用（免费计划、自托管、本地后端）时回退到 Convex 环境中配置的服务商密钥。
• 绝不在客户端暴露服务商 API 密钥；需要密钥时（嵌入、网关回退），通过 env micro power 保存在 Convex 环境中。
• 在 action 中执行模型调用（若 SDK 需要，使用 'use node'）。
• 在 Convex 中持久化线程/消息，以获得持久性与响应式能力。

适用场景 适用于需要在应用内集成 AI 智能体、对话机器人和基于文档检索的问答后端的场景，尤其是希望由平台托管模型凭据、避免在前端管理密钥的项目。

限制

• 默认网关方式需要 Convex 1.45+ 且在 Convex Cloud 上使用付费计划。
• 网关目前不提供嵌入服务，RAG 的嵌入部分仍需自行提供服务商密钥。
• 免费计划、自托管或本地后端需回退到服务商密钥方式。