Mastra

前端AI生态框架包括LangChain.js/LangGraph.js（智能体编排）、RAGFlow.ts（RAG工程）、Mastra（Agent开发）、LlamaIndex.ts（数据索引与检索层）

Mastra 底层使用 Vercel AI SDK 的 @ai-sdk/openai-compatible provider 与自定义端点通信，请求发送到 /v1/chat/completions，user agent 为 ai-sdk/openai-compatible。

Mastra 支持通过将 model 字段设为包含 id、url、apiKey 的对象来指向自定义 OpenAI 兼容端点，无需额外 provider 包。

将 agent 的 errorProcessorDefaults 设为 false 或在 generate 调用中传入 errorProcessors: []，可以在 Mastra 中关闭外层错误处理器重试。

Mastra 的 AI SDK 重试层在遇到 429 时会遵守 Retry-After 响应头。

在 Mastra 中，modelSettings.maxRetries 设为 5 且保留默认错误处理器时，一次上游 503 故障会导致 18 次请求、约 99 秒等待。

Mastra 存在两层重试机制：AI SDK 的 modelSettings.maxRetries（默认在 Mastra 中为 0）和 Mastra 默认错误处理器（额外重试两次，间隔约三秒），两层同时开启时失败请求会相乘放大。

Mastra agent 遇到 401 错误时会立即失败，不进行重试。

Mastra agent 的工具调用循环在达到默认步数上限（5 步）后会静默停止，返回空 text 且 finishReason 为 "tool-calls"，不抛错也不打日志。

在 Mastra model 配置中设置 api: "responses" 会让 agent 改为 POST 到 /v1/responses 并使用 input 数组替代 messages。

在 Mastra 自定义 model 配置中省略 apiKey 时，不会回退读取环境变量，请求将不带 Authorization 头，导致 401。

Mastra 不会自动为 url 补全 /v1 路径，用户必须在 url 中自行包含 /v1，否则请求会发到 /chat/completions 而非 /v1/chat/completions。

Mastra 的 model id 中第一个斜杠之前的部分会被剥掉，只有后面的内容作为 model 字段发送给端点。

Mastra 使用对象形式配置 model 时，不会发起 GET /v1/models 探测，也不会添加多余参数。

Mastra 的 agent.generate 支持通过 maxSteps 参数控制工具调用循环的最大轮数。

Mastra 与 LangGraph 的选择应基于 Agent 流程的拓扑复杂度而非生态偏好：线性任务用一体化框架更轻，多分支、需回滚的流程更适合图结构。

Mastra 是 TypeScript 优先的 Agent 框架，提供工作流、工具、记忆与 RAG 等一体化能力。

LangGraph 的图状态天然适合映射为事件流中的状态更新事件；Mastra 的工作流步骤更贴近工具调用事件的粒度。

Mastra 和 AI SDK 更偏向轻量级编排，对简单链式和路由支持直接，复杂模式需要自行组合。

Mastra 是一个面向 TypeScript 的 Agent 开发框架，内置评估模块，与 Agent 运行时深度耦合，能直接拦截和记录每次工具调用的详细信息。