用途
convex-agents 用于在 Convex 平台上构建 AI 智能体与助手。根据资料，其适用场景包括：实现聊天界面、AI 助手、工具调用（tool-calling）智能体，以及 RAG（检索增强生成）。
主要能力
该技能以代码示例的形式覆盖以下能力：
-
基础聊天数据结构：在
convex/schema.ts中定义threads与messages两张表。threads包含userId、可选title、createdAt、updatedAt，并建立by_user索引；messages包含threadId、role（user/assistant/system）、content、createdAt，并建立by_thread索引。 -
线程管理：在
convex/threads.ts中提供create（mutation，需登录，未认证时抛出 ConvexError）、list（query，按用户索引倒序返回线程）、getMessages（query，按线程索引正序返回消息）。 -
AI 集成（Actions）：在
convex/ai.ts中使用"use node"与 OpenAI SDK，通过internalAction实现chat，流程为保存用户消息、读取历史、调用 OpenAI 聊天补全、保存助手回复；配套saveMessage（internalMutation，同时更新线程时间戳）与getHistory（internalQuery）。 -
流式响应：
streamChat先保存用户消息并创建空的助手消息占位，再以stream: true调用 OpenAI，逐块累积内容，约每 500ms 通过updateMessage更新一次，最后做一次最终更新。 -
工具调用 / 函数调用：定义
tools数组（示例包含search_documents与create_task），在chatWithTools中调用带tools的聊天补全；当finish_reason为tool_calls时解析参数并分发执行，示例中分别调用内部搜索 action 与任务创建 mutation，并返回结果文本。 -
RAG（检索增强生成）：在 schema 中为
documents表定义content、embedding（float64 数组）、metadata，并建立by_embedding向量索引（示例维度 1536，对应 OpenAI ada-002）。convex/search.ts提供embed（调用 text-embedding-ada-002 生成向量）、indexDocument、saveDocument、search（先嵌入查询再向量检索，默认 limit 5）与vectorSearch（使用withSearchIndex与q.vector(...).limit(...)，返回内容与_score）。ragChat示例先检索相关文档，拼接为上下文，再构造带上下文的 system 提示词继续对话。
使用方式
资料以 TypeScript 代码片段呈现，涉及 Convex 的 schema、mutation、query、internalAction、internalMutation、internalQuery 等函数类型，以及 OpenAI SDK 的调用方式。API 密钥通过环境变量（如 process.env.OPENAI_API_KEY）读取。资料未提供安装命令或具体部署步骤。
适用场景
适合以 Convex 为后端、需要构建对话式 AI 应用的开发者，尤其是需要线程化聊天记录、流式输出、工具调用或基于向量检索的知识问答的场景。
限制与注意事项
资料列出常见陷阱：不要在客户端放置 API 密钥，应使用带 "use node" 的 action 发起 API 调用；长对话需实现上下文窗口控制或摘要；需处理 API 速率限制与失败；应准备非流式的降级方案；发送给 LLM 的消息历史应有上限。
参考链接
- Actions: https://docs.convex.dev/functions/actions
- Vector Search: https://docs.convex.dev/search/vector-search
- Environment Variables: https://docs.convex.dev/production/environment-variables
关于收费、价格、平台支持范围等信息，资料暂未提供。