SuperAPI AI 工具集

mastra

智能体与模型

查看项目

更新于 10-26 16:17

技能介绍

Mastra 是一个用于构建 AI 应用的 TypeScript 框架,通过统一的 Mastra() 构造函数将智能体、工作流、工具、记忆、RAG、MCP、语音、评估和可观测性等功能整合在一起。项目可通过 npm create mastra@latest 创建,使用 mastra dev 启动开发服务器,Studio 界面默认运行在 localhost:4111。框架基于 Hono,可部署到 Node.js 22+、Bun、Deno、Cloudflare、Vercel、Netlify、AWS 和 Azure。

主要能力包括:

  • 智能体:使用 new Agent({}) 创建,接受 instructions、模型字符串(如 'openai/gpt-4.1')和可选工具。通过 agent.generate() 获取完整响应,或通过 agent.stream() 流式输出,两者都支持 maxSteps(默认 5)限制工具调用循环。
  • 工作流:使用 createWorkflow() 和 createStep() 构建带类型的多步骤管道。步骤具有 Zod inputSchema/outputSchema,通过 .then() 链接、.branch() 分支、.dountil()/.dowhile() 循环、.parallel() 并行、.foreach() 迭代,并且必须在末尾调用 .commit()。
  • 工具:通过 createTool({ id, description, inputSchema, outputSchema, execute }) 创建带类型的函数,description 字段用于引导 LLM 选择工具。
  • 记忆:支持消息历史、工作记忆(持久用户画像)、观察记忆(后台摘要)和语义召回(对历史对话的 RAG)四种类型,通过 new Memory({}) 配置。
  • MCP:MCPClient 可连接外部工具服务器,MCPServer 可将 Mastra 工具/智能体暴露为 MCP 端点。listTools() 用于静态单用户场景,listToolsets() 用于动态多用户场景。

使用方式:新项目运行 npm create mastra@latest,现有项目运行 npx mastra init --components agents,tools,workflows --llm openai。环境变量中至少需要一个 LLM 提供商的密钥(如 OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_GENERATIVE_AI_API_KEY 或 OPENROUTER_API_KEY),可选配置 POSTGRES_CONNECTION_STRING 用于 pgvector RAG/记忆,或 PINECONE_API_KEY 用于 Pinecone 向量存储。CLI 命令包括 mastra dev(开发服务器与 Studio)、mastra build(打包到 .mastra/output/)、mastra build --studio(构建中包含 Studio UI)、mastra start(服务生产构建)、mastra lint(验证项目结构)、mastra migrate(运行数据库迁移)。

适用场景:创建或配置带工具、记忆或结构化输出的 Mastra 智能体;定义带步骤、分支、循环或并行执行的工作流;使用 createTool 和 Zod 模式创建自定义工具;设置记忆(消息历史、工作记忆、语义召回);构建 RAG 管道(分块、嵌入、向量存储);配置 MCP 客户端连接外部工具服务器;将 Mastra 智能体/工具暴露为 MCP 服务器;运行 Mastra CLI 命令;将 Mastra 应用部署到任何云提供商。

限制与注意事项:该技能不适用于与 Mastra 无关的通用 TypeScript/Node.js 问题,也不适用于其他 AI 框架(LangChain、CrewAI、AutoGen),除非与 Mastra 进行比较。工作流链末尾必须调用 .commit(),否则会静默无操作。应通过 mastra.getAgent('id') 访问智能体,直接导入会绕过日志、遥测和注册资源。mcp.listTools() 在初始化时缓存工具,服务器工具变更后需重启进程才能看到新工具;多用户动态场景应使用 mcp.listToolsets() 并在请求后调用 mcp.disconnect()。记忆资源 ID 必须唯一,否则可能导致跨用户数据泄漏。工作流步骤模式不匹配会在运行时抛出 Zod 解析错误,需使用 .map() 转换数据形状并在开发时验证。访问 result.result 或 result.error 前应检查 result.status(可能值:success、failed、suspended、tripwire、paused)。详细子域内容可参考 references/ 文件夹中的文件(workflows-advanced.md、memory-and-rag.md、mcp-and-voice.md、deployment-and-server.md),仅在任务需要时加载以避免消耗上下文。首次激活时检查伴随技能安装情况,缺失的可通过 npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name> 安装。