Mastra 框架完全指南：用现代 TypeScript 构建 AI 应用与智能体

Mastra 框架完全指南用现代 TypeScript 构建 AI 应用与智能体【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 是一个面向 AI 应用与 Agent 的现代 TypeScript 框架提供了从模型路由、自主 Agent、图式工作流编排到人机协同、RAG 上下文管理、MCP 服务发布以及评测与可观测性的全链路能力。本指南以仓库根目录 README.md 为主线结合mastra/core的源码实现帮助你掌握 Mastra 的核心抽象、快速初始化一个生产级项目并理解其底层设计原理读完即可上手构建、调优与规模化你的 AI 产品。Mastra 是什么Mastra 是一个用于构建 AI 应用和 Agent 的框架采用现代 TypeScript 技术栈其定位是从早期原型到生产级应用提供开箱即用所需的一切。它可以与 React、Next.js、Node 等前端与后端框架集成也可以作为独立服务器部署到任意环境官方将其描述为“构建、调优和扩展可靠 AI 产品的最简单方式”。从仓库的模块划分可以直观看到框架的覆盖面packages/core是框架内核Agent、Workflow、LLM 路由、Memory、Storage、Evals、MCP、Voice 等packages/rag、packages/memory、packages/evals、packages/mcp等是分立的进阶包client-sdks/react与client-sdks/ai-sdk提供前端集成server-adapters/下则提供了 Express、Fastify、Hono、NestJS、Next、Elysia、Koa 等服务端适配器。为什么选择 MastraREADME 中给出了 Mastra 的核心设计主张专为 TypeScript 构建并围绕成熟的 AI 模式设计开发者无需从零组装模型调用、工具执行、状态持久化与评测观测等基础设施。仓库的packages/core/src目录结构源码目录印证了这一设计——agent/、workflows/、llm/、memory/、storage/、evals/、observability/、mcp/等模块彼此独立又可组合构成了一个完整的 AI 应用框架体系。七大核心能力速览README 将 Mastra 的高亮特性归纳为以下几项下面逐一结合源码展开。1. 模型路由Model Routing一个标准接口连接 40 提供商通过统一的模型接口可以接入 OpenAI、Anthropic、Gemini 等 40 余家模型提供商覆盖数千个模型。这一能力的核心实现在 packages/core/src/llm/model/router.tsModelRouter从源码可以看到它封装了 AI SDK v5/v6/v7 多个版本的语言模型适配层并内置defaultGateways与GatewayManager处理模型网关gateway的鉴权与流式传输例如MASTRA_GATEWAY_STREAM_TRANSPORT支持 WebSocket 流式传输。在 packages/core/src/mastra/index.ts 的Config接口注释示例中Agent 的模型直接以字符串指定new Agent({ id: weather-agent, name: Weather Agent, instructions: You help with weather information, model: openai/gpt-5 // 统一格式provider/model })provider/model这种统一寻址格式意味着更换模型提供商时只需改动配置字符串业务代码无需变动。2. Agent自主智能体Agent 是使用 LLM 与工具解决开放式任务的自主系统。其行为模式为Agent 推理目标 → 决定使用哪些工具 → 内部迭代直到模型输出最终答案或命中可选的停止条件。Agent 的完整实现在 packages/core/src/agent/agent.ts约 1 万行涵盖生成、流式输出、工具调用、记忆、持久化、信号、子 Agent 等类上还挂载了输入/输出处理器Processor、技能系统SkillsProcessor、请求上下文RequestContext等机制。Agent 可以引用其他 Agent 作为子 Agentsubagent.ts也能通过网络循环loop/network.ts组成多 Agent 协作网络仓库内对应agent-network.e2e.test.ts、agent-network.test.ts测试。3. Workflow显式控制执行的图式工作流引擎当需要显式控制执行流程时Mastra 提供基于图的工作流引擎来编排复杂的多步骤过程。其核心语法是直觉化的控制流.then()串行、.branch()条件分支、.parallel()并行。工作流工厂实现在 packages/core/src/workflows/create.ts其中的类型化示例清晰展示了基本用法import { createWorkflow } from mastra/core/workflows; import { z } from zod; const workflow createWorkflow({ id: greeting, inputSchema: z.string(), outputSchema: z.string(), }).then(yourStep).commit();关键点createWorkflow会生成类型安全的步骤链——每个步骤的输入输出都有 schema 约束并在.commit()时完成注册。从 packages/core/src/workflows/workflow.ts 的源码注释可以看到完整控制流还包括.dowhile()、.dountil()等循环结构并支持声明式PredicatepredicateToCondition将声明式谓词包装为运行时条件回调。mapVariable则用于在步骤间精确引用上游输出或initData中的字段。此外声明schedule定时调度会自动切换到 evented 事件驱动引擎create.ts从而支持定时工作流。仓库的 examples/agent/README.md 还展示了动态工作流Dynamic Workflow——从 JSONDynamicWorkflowGraph声明式重建工作流支持foreach、conditional、嵌套子工作流并通过mastra.addDynamicWorkflow(...)持久化到WorkflowDefinitionsStorage服务重启后依然存在。4. 人机协同Human-in-the-loop挂起与恢复可以挂起suspend一个 Agent 或工作流等待用户输入或审批后再恢复执行。关键在于 Mastra 使用存储storage记住执行状态因此可以无限期暂停然后从上次离开的位置继续。这一能力在源码中有直接体现packages/core/src/workflows/下存在suspend、resume相关实现与大量测试如nested-resume-label.test.ts、concurrent-resume.test.ts、timetravel-divergence.test.tspackages/core/src/agent/下也有resume-span-input.ts等恢复输入的处理逻辑。存储层则由packages/core/src/storage/MastraCompositeStore及各域实现如domains/workflows、domains/inmemory-db承载。5. 上下文管理Context Management在正确的时机给出正确的上下文Agent 的上下文质量直接决定输出质量Mastra 提供三层能力会话历史conversation history由packages/core/src/memory/与packages/core/src/agent/message-list/实现支持线程化的消息列表管理检索retrieve从 API、数据库、文件等数据源检索数据注入上下文对应packages/rag包与packages/core/src/vector/向量存储抽象MastraVector以及packages/core/src/rag相关模块观察式记忆Observational Memory让 Agent 拥有类人的连贯记忆行为使 Agent 在不同会话间表现一致。内存Memory的存储后端可插拔仓库stores/目录下提供了超过 25 种存储实现包括 PostgreSQLstores/pg、Redisstores/redis、MongoDBstores/mongodb、ClickHousestores/clickhouse、DynamoDBstores/dynamodb、LibSQLstores/libsql、Cloudflare D1stores/cloudflare-d1等。6. 集成Integrations嵌入现有应用或独立发布Mastra 的 Agent 与工作流可以打包进现有的 React、Next.js 或 Node.js 应用作为独立端点standalone endpoints对外发布构建 UI 时与 Vercel AI SDK UI、CopilotKit 等 Agentic 库集成。客户端侧仓库提供了client-sdks/reactReact Hooks 与 UI 组件、client-sdks/ai-sdkAI SDK 适配与client-sdks/client-js服务端侧则通过server-adapters/对接主流 Node 框架。7. MCP 服务通过标准协议暴露 Agent 与工具Mastra 支持编写Model Context ProtocolMCP服务器通过 MCP 接口暴露 Agent、工具及其他结构化资源任何支持该协议的系统或 Agent 都能访问它们。相关实现位于 packages/core/src/mcp/ 与独立的packages/mcp包另有一个packages/mcp-docs-server用于为文档提供 MCP 服务。Config接口中同样定义了mcpServers注册项见 packages/core/src/mastra/index.ts。8. 生产必备评测与可观测性可靠的 AI 产品依赖持续的洞察、评测与迭代。Mastra 内置Evals评测packages/core/src/evals/与packages/evals包提供评分器Scorer、阈值判定、hook 钩子等用于度量 Agent 输出质量Observability可观测性packages/core/src/observability/提供基于 span 的追踪体系createObservabilityContext、getOrCreateSpan等observability/目录下还有针对 Langfuse、LangSmith、Arize、Datadog、Sentry、Braintrust、PostHog 等十余家观测平台的集成包。快速开始一分钟创建第一个 Mastra 项目README 推荐的起步方式是一行命令npm create mastralatest这条命令对应仓库中的packages/create-mastra脚手架。关于它的更多细节见 create-mastra 的 READMENode.js 版本要求22.13.0或更高各包管理器等价命令# npm npx create-mastralatest # Yarn yarn dlx create-mastralatest # pnpm pnpm create mastralatestcreate-mastra是一次性项目生成器无需预先安装交互式向导会询问项目创建位置并帮助配置初始 Mastra 目录、示例 Agent、模型提供商以及可选的开发工具传--help可查看非交互选项。README 还提供了一个可直接用于 AI 编程助手的预置提示词pre-built prompt其流程概括如下询问项目名默认my-mastra-app询问模型提供商支持openai、anthropic、google、xai不支持则重新列出可选值执行npm create mastralatest project-name -- --llm provider创建项目会自动安装检测到的编码助手对应的 Mastra 技能并在适当时初始化 Git进入项目目录启动开发服务器npm run dev打开Mastra Studiohttp://localhost:4111——Studio 是用于构建、测试和管理 Agent、工作流与工具的图形化界面。深入实战Mastra 实例配置与 Agent / Workflow 组合初始化后的项目通常会在src/mastra/下定义 Agent 与 Workflow并用Mastra实例统一注册。Mastra类从 packages/core/src/index.ts 导出export { Mastra, type Config }。Mastra 实例的 Config 结构Config接口定义packages/core/src/mastra/index.ts给出了所有可注册组件配置项类型说明agentsRecordstring, Agent注册 Agent 实例也接受 AI SDK v6 ToolLoopAgent 与 DurableAgent 包装workflowsRecordstring, Workflow注册工作流实例vectorsRecordstring, MastraVector向量存储用于语义检索与 RAGstorageMastraCompositeStore持久化数据、会话历史与工作流状态的存储Agent 记忆与工作流持久化的前提loggerIMastraLogger \| false日志实现设为false可完全关闭日志默认开发环境INFO、生产环境WARNmcpServersRecordstring, MCPServerBase注册 MCP 服务器scorersRecordstring, MastraScorer注册评测评分器toolsRecordstring, ToolAction注册工具processorsRecordstring, Processor注册输入/输出处理器memoryRecordstring, MastraMemory注册记忆实例官方注释示例中一个最小可用的组合如下const mastra new Mastra({ agents: { weatherAgent: new Agent({ id: weather-agent, name: Weather Agent, instructions: You help with weather information, model: openai/gpt-5 }) }, storage: new LibSQLStore({ id: mastra-storage, url: :memory: }), logger: new PinoLogger({ name: MyApp }) });注意logger与可观测性的集成方式源码Config注释中的loggerTelemetryOptions支持correlation在 span 活跃时将trace_id/span_id注入日志与export将日志导出到 Mastra 观测存储/导出器两种模式。组合 Agent 与 Workflow 的典型形态生产项目中Agent 负责开放式的推理任务Workflow 负责确定性的编排。仓库 examples/agent 是官方示例项目其 READMEexamples/agent/README.md提供了可运行的参考示例内含计算机使用 AgentComputer-use Agent通过 Daytona 或 E2B Desktop 远程控制 Linux 桌面、请求上下文预设Request Context Presets可在 Studio 中一键切换不同环境/角色的上下文配置以及动态每日站会摘要工作流daily-standup-digest。示例项目常用的开发命令同样适用于create-mastra生成的项目pnpm mastra:dev # 启动 Mastra 开发服务器 pnpm mastra:studio # 打开 Mastra Studio UI pnpm mastra:build # 生产构建 pnpm mastra:start # 启动生产服务器日常迭代流程是mastra dev启动开发服务器 → 在http://localhost:4111的 Studio 中测试 Agent 与工作流 →mastra build构建 → 通过server-adapters/如mastra/hono、mastra/express或packages/deployer部署。仓库结构导航从源码理解 Mastra如果你希望深入源码仓库根目录 package.json 展示了这是一个基于pnpm turbo的 monorepo要求 pnpm 11使用pnpm-workspace.yaml管理工作区。主要模块与目录对应关系如下框架内核packages/core/srcAgent、Workflow、LLM、Memory、Storage、Evals、Observability、MCP、Voice、Channels 等进阶能力包packages/ragRAG、packages/memory记忆、packages/evals评测、packages/mcpMCP 工具与服务端、packages/loggersPino 等日志器、packages/deployer部署客户端 SDKclient-sdks/react、client-sdks/ai-sdk、client-sdks/client-js服务端适配器server-adapters/express、fastify、hono、nestjs、next、koa、elysia、tanstack-start存储后端stores/pg、redis、mongodb、libsql、clickhouse、dynamodb 等 25 实现观测集成observability/langfuse、langsmith、datadog、sentry、arize、braintrust、posthog 等语音能力voice/deepgram、elevenlabs、openai、azure、google 等示例examples/agent综合性示例项目、templates/20 可复用模板如文档问答、Deep Search、GitHub 代码评审 Agent、Slack Agent 等。构建与测试脚本同样集中在根 package.jsonpnpm build通过 turbo 并行构建所有包pnpm test:core、pnpm test:server、pnpm test:evals、pnpm test:memory等按模块细分测试。许可证与安全本仓库采用双许可证模式Apache License 2.0框架核心及绝大部分代码Mastra Enterprise License任何名为ee/的目录例如packages/core/src/auth/ee/下的代码为源码可用source-available生产环境使用需有效的企业许可证但开发与测试可免费使用。完整许可映射见 LICENSE.md企业许可条款见 ee/LICENSE。安全问题上仓库鼓励通过securitymastra.ai负责任地披露漏洞。参与贡献与获取支持贡献指南所有类型的帮助编码、测试、特性规格都受欢迎详见 CONTRIBUTING.md——其中明确要求提交 PR 前先在 issue 中讨论且 PR 描述必须关联对应 issue如Fixes #1234、Closes #1234开发者可参考 DEVELOPMENT.md 完成本地开发环境搭建。Bug 复现CONTRIBUTING 强调使用“最小复现”项目只包含触发问题的包、最小配置与代码新项目可用npx create-mastralatest bug-reproduction快速创建或从examples/中裁剪。社区支持官方 Discord 社区discord.gg/mastra-ai提供开放式交流。小结Mastra 的核心价值在于以 TypeScript 类型系统贯穿模型路由、Agent、Workflow、记忆与存储、评测与观测的完整链路让你把精力集中在 AI 应用的业务逻辑上而非基础设施胶水代码。从 README.md 的框架总览出发结合本指南中的源码路径你可以按“npm create mastralatest初始化 → Studio 中迭代 →server-adapters或deployer部署”的路径快速进入生产级 AI 应用的构建流程。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考