前四个系列——Agent 开发、上下文工程、EDD、本地部署——全部泡在 Python 生态里：LangGraph、LlamaIndex、Ollama，工具链用得很顺手。但这个系列要换枪了：TypeScript + Mastra。原因很直接：2026 年 TypeScript 已经是全栈默认语言之一，大量团队的现状是 Next.js 前端加 Node 后端，一条流水线一种语言；为了上 Agent 单独养一个 Python 微服务，换来的是两套依赖、两套 CI 和一条类型断裂的序列化边界。
Mastra 是 TypeScript Agent 框架目前的事实领跑者：ex-Gatsby 团队打造、YC W25、开源 Apache-2.0，把 agents、workflows、memory、tools、MCP、evals、tracing 装进同一个框架。本篇是系列第 1 篇，按"为什么 → 是什么 → 怎么选 → 怎么跑"组织：先论证为什么需要 TS Agent 框架，再画 Mastra 全景，对比 LangGraph 划清甜区，速览五大核心概念，最后跑通第一个 Agent 并给出 14 篇路线图。
1、为什么需要 TS Agent 框架
先摆问题。全栈 TS 团队要上 Agent，过去只有两条路。一是把 Agent 逻辑放进 Python 服务，FastAPI 加 LangGraph 几乎是标配，前端走 HTTP 调用；二是用 LangChain.js 之类的移植库在 Node 里硬写。
第一条路的代价是架构分裂：两套运行时、两套依赖管理、两套监控，工具定义每改一次都要跨服务同步接口。类型安全在边界断裂是这里最疼的一点：Python 侧用 Pydantic 定义工具入参，TS 前端还得手写一遍 TypeScript 类型，两边靠人肉约定保持一致。改了一边忘了另一边，就是运行时才爆出来的线上事故。
第二条路缺的是框架层。Vercel AI SDK 解决的是模型调用层——streaming、tool call 协议、多 provider 适配，做得很好；但它不管 Agent 的编排、记忆、评测和追踪，而这些恰恰是 Agent 从 demo 走向生产的主战场。中间空出来的位置，就是 Mastra 站的地方。
TS 原生框架最大的红利是Zod schema 贯穿工具与输出：同一个 Zod schema，前端拿它做表单校验，Agent 工具拿它定义入参出参，结构化输出拿它约束模型返回。类型从 UI 一路静态推导到模型输出，全程零手写同步——这是 Python 生态给不了的端到端体验，Pydantic 只覆盖了后端半截。
顺带说一句工程土壤：2026 年的 TS 工具链已经不是短板。Bun 和 pnpm 把 monorepo 工程化拉平，tRPC 让前后端接口全程类型化，剩下的缺口只有 Agent 框架这一块——补上它，整条链路才算真正闭环。
2、Mastra 框架全景
先给事实底座。Mastra 是开源框架（Apache-2.0），代码在 GitHub 仓库，官网文档齐全。团队来自 Gatsby：联合创始人 Sam Bhagwat 曾任 Gatsby 的 COO，Gatsby 当年融了 5000 万美元、最后卖身 Netlify。公司入选 YC W25，2026 年又拿下 Spark Capital 领投的 2200 万美元 A 轮，累计融资约 3500 万美元。版本方面，截至 2026 年 10 月，@mastra/core 稳定在 1.x 线，npm 最新 1.79.0；CLI 与脚手架 create-mastra 同步在 1.35.0，要求 Node 22.13 以上。
一句话定位：TS 优先、batteries-included 的一体化 Agent 框架——TypeScript 原生，七大件全配齐，装上电池就能跑。它的能力地图如下：
框架本体 @mastra/core（七大件）
├── Agent —— 模型 + 工具 + 指令的封装
├── Tool —— Zod schema 定义的工具
├── Workflow —— 图式流程编排
├── Memory —— 线程级记忆与语义检索
├── MCP —— 标准协议接入外部工具
├── Evals —— Agent 行为评测
└── Tracing —— OpenTelemetry 链路追踪
解读一下：这七件套覆盖了 Agent 生产化的完整链路——跑（Agent、Tool）、编排（Workflow）、记（Memory）、连（MCP）、测（Evals）、看（Tracing）。本系列后面会逐个展开。
底座选型也值得说：模型接入直接复用 Vercel AI SDK 的 provider 生态，OpenAI、Anthropic、Google、本地 Ollama 一个 import 就切换；HTTP 服务层用 Hono；schema 层 Zod v3、v4 都支持。不在成熟层重复造轮子，把研发火力集中在 Agent 特有的问题上，这是它能一年多跑到 1.x 稳定线的原因之一。
3、与 LangGraph 的定位差异
Agent 系列第 25 篇的框架对比表里给过一句话结论：Mastra 是"TS 原生、batteries-included"。从 TS 视角展开，核心差异可以压成两组词：约定优先 vs 图即代码，DX 优先 vs 控制权优先。
LangGraph 的哲学是图即代码：在 StateGraph 上显式声明节点和边，状态对象贯穿全图，任意转移边、循环、检查点都能精确表达。代价是样板多、心智模型重——你得先学会图，再学会 Agent。Mastra 反过来：new Agent 三行就能跑，顺序、条件分支、并行、人机协同这些常见编排在 Workflow 里是现成原语，需要更细控制时再把图展开。
| 维度 | Mastra | LangGraph |
|---|---|---|
| 语言 | TypeScript 原生 | Python 为主，JS 版跟随 |
| 核心抽象 | Agent 约定 + Workflow | StateGraph 状态图 |
| 上手成本 | 低，脚手架开箱即用 | 中，先懂图再懂 Agent |
| Schema | Zod 贯穿前后端 | Pydantic，止步后端 |
| 控制粒度 | 常见模式已封装 | 任意边与状态转移 |
| 生态配套 | 七件套一体化 | LangChain 全家桶 |
各自的甜区很清楚：做复杂多阶段研究流水线、需要精确控制每一步转移与回溯，LangGraph 依然是天花板；把 Agent 能力快速嵌进现有 TS 产品、团队没有专职 AI 工程师，Mastra 的上手速度优势明显。两者也不互斥：不少团队 Python 侧跑 LangGraph 做重流程，TS 侧用 Mastra 做产品集成，各守各的甜区。
4、核心概念速览
五大概念，每个一段简介，后续各有专篇展开。
Agent 是框架的一等公民：模型、工具集、指令（instructions）三件东西打包成一个对象。generate() 同步拿结果，stream() 流式输出，模型何时调工具由框架的工具循环驱动。多 Agent 组网与交接也建立在它上面。
Tool 用 createTool 定义：Zod 的 inputSchema、outputSchema 约束入参出参，execute 里写业务逻辑。schema 即文档即校验——模型读 description 决定何时调用，编辑器里全程类型推导。
Workflow 做图式编排：把多个 step 按 DAG 连起来，支持条件分支、并行、失败重试。亮点是 suspend 与 resume：流程可以挂起等人审批再继续，这是人机协同的原生原语。
Memory 以**线程（thread）**为单位组织对话历史：resourceId 标用户、threadId 标会话，两级隔离。存储后端可换 LibSQL、Postgres 等，向量检索可挂载，长对话压缩、语义回忆都封装在统一接口后面。
MCP（Model Context Protocol）让 Mastra 作为 client 接入任意外部 MCP 服务器，一份配置把第三方工具变成 Agent 工具；方向反过来也行——把 Mastra 服务本身暴露成 MCP server 给其他客户端用。协议细节见 MCP 规范。
5、生态三件套
学 Mastra 要先分清三个东西：框架本体、开发工作台、部署形态。
第一件是框架本体：@mastra/core 加 CLI 包 mastra，npm create mastra@latest 一条命令装好。脚手架会生成 agent 定义、注册 Mastra 实例的入口文件和开发配置，还能顺手集成 Next.js 前端模板。
第二件是 Mastra Dev，本地开发工作台：项目里跑 mastra dev，服务起在 4111 端口，浏览器打开就是 Playground——和 Agent 对话调试、直接调用工具、查看每一步的 trace，代码改动热更新。它的体验接近"Agent 版的数据库 GUI"，用过一次基本回不去。
第三件是部署：mastra build 产出基于 Hono 的独立 Node 服务，PM2、Docker 随便托管；官方 deployer 可以打包成 Vercel、Cloudflare 等 Serverless 函数；另有官方托管云负责运行时与状态。本地调试、自托管、托管云三条路，按团队规模选。
选型建议很朴素：个人项目和中小团队直接上 Vercel 或 Cloudflare 的 deployer，零运维；有合规或数据边界要求的，走自托管 Node 服务；等多 Agent 需要共享运行时和状态时，再评估托管云。三条路之间迁移的成本不高，因为产物始终是同一套 @mastra/core 代码。
6、第一个 Agent 实测
从安装开始，一条命令拉起项目：
npm create mastra@latest weather-bot
cd weather-bot
解读：脚手架生成标准目录，agent 与工具定义放在 src/mastra/ 下，依赖自动安装，.env 里填上 OPENAI_API_KEY 即可就绪。核心代码只有一个工具加一个 Agent，如下：
import { Agent } from '@mastra/core/agent';
import { createTool } from '@mastra/core/tools';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
const weatherTool = createTool({
id: 'get-weather',
description: '查询指定城市的实时天气',
inputSchema: z.object({ city: z.string() }),
execute: async ({ context }) => {
// 演示用假数据，生产环境换真实天气 API
return { city: context.city, temp: 18, condition: '晴' };
},
});
export const weatherAgent = new Agent({
name: 'weather-agent',
instructions: '你是天气助手，回答前必须先查实时数据',
model: openai('gpt-4o'),
tools: { weatherTool },
});
这段代码有两个要点。其一，context.city 自动推导为 string，是 Zod schema 带来的类型红利；其二，openai('gpt-4o') 一个工厂函数接好 provider，换模型只改一个字符串。跑起来同样直接：
const result = await weatherAgent.generate(
'北京今天适合穿外套吗？',
);
console.log(result.text);
Agent 会在需要时自动调用工具、拿回数据再组织回答：result.text 是最终自然语言，result.toolCalls 能看到中间的调用记录。最后是工作台模式：
npx mastra dev
启动后浏览器访问 http://localhost:4111，在 Playground 里选中 weather-agent 直接对话，右侧能看到完整的工具调用轨迹——比对着 console.log 猜流程强一个量级。
注意：Mastra 处在 1.x 快速迭代期，minor 版本间偶有 API 调整。本文代码以 1.79 版为基准，动手前建议先过一眼官方文档对应章节。
7、系列路线图
系列共 14 篇，四条主线推进：
- 第 1 篇：全景导览（本篇）
- 第 2 篇：环境搭建——脚手架与项目结构
- 第 3 篇：Agent 核心——模型、指令与生成模式
- 第 4 篇：Tool 开发——Zod schema 与错误处理
- 第 5 篇：结构化输出——outputSchema 实战
- 第 6 篇：Memory——线程记忆与语义检索
- 第 7 篇：Workflow 基础——图式编排入门
- 第 8 篇：Workflow 进阶——suspend 与人机协同
- 第 9 篇：MCP——接入外部工具服务器
- 第 10 篇：多 Agent 协作——组网与交接
- 第 11 篇：Evals——给 Agent 写回归测试
- 第 12 篇：Tracing——OpenTelemetry 可观测
- 第 13 篇：部署——Node 服务与 Serverless
- 第 14 篇：实战——生产级 Agent 从零到上线
节奏是：先把单 Agent 跑透（第 2～5 篇），再解决状态与编排（第 6～8 篇），然后打通外部世界（第 9～10 篇），最后补齐工程化（第 11～14 篇）。每篇都有可运行代码，实战篇合成一个完整项目。
8、总结
本篇做了四件事：论证了全栈 TS 团队为什么值得一个原生 Agent 框架——类型安全端到端、不用引入第二技术栈；给出 Mastra 的定位与版本事实——ex-Gatsby 团队、1.x 稳定线、七大件一体化；用"约定优先 vs 图即代码"划清了它与 LangGraph 的甜区；最后用二十行代码跑通了第一个带工具的 Agent。
判断自己该不该入 TS 栈，问三个问题：团队主力语言是不是 TypeScript；Agent 是嵌进现有产品，还是独立的研究流水线；有没有精力维护第二个技术栈。对于 Next.js 加 Node 的产品团队，建议直接花半天跑通本文的 weather-bot，再用 Mastra Dev 工作台玩一天，体感会比任何横评文章都准；对于重 Python 的算法团队，LangGraph 依然是主场，Mastra 值得了解但不必迁移。下一篇我们从脚手架生成的项目结构开始，把每一层代码摊开讲。
