Mastra：用 TypeScript 把 AI Agent 从原型带进可维护的应用程式

我一直觉得，AI Agent 最难的部分不是让模型「回答一次」，而是把它放进一个真正会被使用的产品：它要知道何时该呼叫工具、何时该交给固定流程、如何保留上下文、如何被观察与评估，还要能和既有的前端、后端及部署方式共存。Mastra 想处理的，正是这段从 demo 到产品的工程落差。

Mastra 是一个以 TypeScript 为核心的 AI 应用程式与 Agent framework。官方 README 将它定位为支援 React、Next.js、Node，以及独立伺服器部署的框架；它把 model routing、agents、workflows、human in the loop、context management、MCP servers、evals 与 observability 放在同一套开发体验里。这个定位很适合 AI Chain 读者：重点不是再介绍一个聊天机器人，而是拆解一个团队如何把 Agent 做成可组合、可测试、可持续维护的软体元件。

先讲结论：Mastra 的价值在于把边界画清楚

如果你的需求是一次性呼叫模型、把回答显示在页面上，Mastra 可能不是必要选择；直接使用模型供应商 SDK 反而更快。但只要需求开始出现以下任一条件，框架化的价值就会上升：Agent 需要使用多个工具，任务有明确的多步骤流程，使用者必须在关键节点核准，团队需要追踪每次执行，或产品同时支援不同模型供应商。

我对 Mastra 的主要判断是：它不是只把 LLM API 包一层，而是提供一个让「不确定的推理」与「确定的程式流程」共存的结构。Agent 适合处理步骤未知的开放式任务；workflow 则把执行顺序、分支与平行处理写成可检查的图。这种分工比「所有事情都丢给一个超级 Agent」更容易除错，也比较容易向产品与资安团队说明。

Mastra 到底提供哪些组件？

1. Model routing：先降低供应商耦合

官方文件使用 provider/model 的字串格式描述模型，例如 openai/某个模型名称。这种介面把模型选择集中在一个可读的设定值，而不是把特定供应商的 provider object 散落在每个 Agent 里。当团队需要比较不同模型，或因为成本、延迟、资料治理而更换供应商时，这个抽象层能减少改动面。

不过，这不代表模型切换没有代价。不同模型在工具呼叫、结构化输出、上下文长度与推理风格上仍可能有差异。model routing 解决的是连接方式与设定管理，不会自动替你完成模型评估。因此我会把它视为「降低切换成本的入口」，而不是「模型品质的保证」。

2. Agents：把开放式任务交给推理回圈

Mastra 官方对 Agent 的定义很清楚：Agent 使用 LLM 与 tools 解决开放式任务，依目标决定要呼叫哪些工具、迭代几次，以及何时停止。你提供的是目标、限制与工具边界，而不是把每一个步骤写死。

最小的 Agent 可以只有 id、name、instructions 和 model。如果要提供工具，官方文件建议用 createTool 建立带有 id、描述、Zod schema 与 execute 的工具，再把工具传入 Agent。这里有一个值得注意的工程原则：工具不是一段随手塞进去的函式，而是具有输入契约与执行边界的介面。对想把 Agent 接到企业资料或外部 API 的团队来说，这是安全性与可测试性的起点。

下面是官方文件概念的精简版本，示范一个只负责回答天气问题的 Agent：

import { Agent } from '@mastra/core/agent'
export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: 'You are a helpful weather assistant.',
  model: 'provider/model-name',
})

这段程式码真正重要的不是名称，而是责任分离：Agent 描述要完成的任务，model 指定推理引擎，工具则在另一个明确的模组中定义。正式专案应再补上错误处理、权限、输入验证、逾时与观测资料，不能把这个最小范例直接当成生产设定。

3. Workflows：把可预测流程写回程式码

当任务的步骤其实是确定的，例如先查询订单、再检查库存、最后产生通知，使用 workflow 比使用一个自由决策的 Agent 更合适。Mastra 的 workflow engine 以图形化的多步骤流程为核心，官方 README 提到可以用 .then()、.branch() 与 .parallel() 表达顺序、分支和平行执行。

这个差异可以用一句话概括：Agent 决定「下一步该做什么」，workflow 规定「哪些步骤可以做、依什么顺序做」。两者不是竞争关系，而是可以互相组合。你可以让 workflow 在固定节点呼叫 Agent，也可以让 Agent 使用一个已经被权限与 schema 约束好的 workflow。

我认为这是 Mastra 最值得写进架构图的部分。很多 Agent demo 看起来很灵活，但一进入产品就会遇到不可重现、难以回溯与无法估算成本的问题。把确定的流程移回程式码，让模型只负责真的需要推理的决策，通常会得到更稳定的系统。

4. Human in the loop：让暂停成为正式状态

真实工作流常常不能完全自动化。例如退款、发送对外讯息、修改权限或提交交易，都可能需要使用者或主管核准。Mastra 支援暂停 Agent 或 workflow，等待输入或批准后再恢复；官方 README 也说明它会透过 storage 保存执行状态，因此流程可以暂停一段时间后再继续。

这和在 prompt 里写「遇到重要事情请先询问」是两回事。Prompt 只是行为建议；可保存的 suspend and resume 状态才是系统能力。前者可能因模型误判而被跳过，后者可以在应用程式层建立真正的审核介面、权限规则与逾时处理。

5. Context、memory 与 RAG：不要把所有资料塞进 prompt

Agent 要做出一致决策，需要在正确时间取得正确上下文。Mastra 将 conversation history、从 API、database 或档案取回资料的 RAG，以及 observational memory 都列为 context management 的一部分。

这里最容易犯的错是把 memory 当成「把所有历史讯息永久塞进上下文」。更好的做法是先定义资料的生命周期：哪些是本轮任务的暂时状态，哪些是使用者偏好，哪些是需要权限控制的企业资料，哪些内容只能透过检索即时取得。框架提供能力，不会替你决定资料保留期限、删除流程、个资遮罩或租户隔离；这些仍然是产品设计与治理责任。

6. Evals 与 observability：从「看起来能跑」到「知道哪里坏」

官方文件将 evals 用于评估 Agent 输出，并提供像是分类、摘要、工具选择与 prompt engineering 等不同方向的 scorer；live evaluations 则可以在 Agent 或 workflow 执行时非同步评分。Observability 则让团队看见每次 Agent run、workflow step、tool call 与 model interaction。

这两者应该一起设计。只做 observability，你会看到系统做了什么，但不一定知道结果是否好；只做 evals，你可能知道分数下降，却找不到是哪个工具、哪个步骤或哪次模型切换造成问题。对生产 AI 来说，trace 是除错材料，eval 是品质讯号，两者都不能等上线后才补。

如何开始：先建立一个可验证的最小专案

Mastra 官方 README 建议使用以下 CLI 建立专案：

npm create mastra@latest

实际上手时，我会采用以下顺序，而不是一开始就把所有功能打开：

1. 准备执行环境。 先确认本机可以执行 npm、能安装套件，并准备你要使用的模型供应商金钥。不要把金钥写入 Git，也不要把它硬编码进 Agent 的 instructions。

1. 用 CLI 建立专案。 先选一个单一用途的 Agent，例如回答内部产品文件问题。第一个任务应该小到可以用三到五个测试案例判断成功或失败。

1. 注册 Agent。 官方文件的基本结构是从 @mastra/core/agent 汇入 Agent，建立 Agent 后，再于 src/mastra/index.ts 以 Mastra 注册。这让同一个 Agent 可以被 workflow、tool 或其他 Agent 取用。

1. 先跑通 Studio。 官方 quickstart 指向 Mastra Studio，启动开发伺服器后可在 http://localhost:4111 开启，用来建立、测试与管理 agents、workflows 和 tools。这个介面很适合先检查工具呼叫与输出，再把整合接到正式 UI。

1. 最后才增加外部工具与记忆。 每加入一个工具，就先定义输入 schema、权限、错误结果与逾时策略；每加入一种 memory，就先写清楚保存什么、保存多久，以及谁可以读取。

第一个可验证任务不应是「做一个万能助理」，而是像「读取指定文件并回答三个固定问题」。这样可以同时验证模型设定、Agent 指令、上下文注入、输出格式与错误处理。完成后，再把单一工具扩展成 workflow，最后才考虑多 Agent 协作。

Agent、workflow、skills 与多代理团队不要混为一谈

这几个词常被放在同一张简报里，但它们解决的层级不同。

Agent 是能根据目标进行推理与工具选择的执行单位，适合步骤未知的任务。
Workflow 是可重跑、可检查的协调逻辑，适合步骤、分支与依赖关系清楚的任务。
Skills 比较像可重用的知识、规则或操作包，让 Agent 知道如何处理某一类工作；它不必然等于一个独立的推理执行个体。
多代理团队 是把多个角色组合起来，可能由一个 coordinator 分派任务，也可能由 workflow 控制顺序。它的复杂度、成本与观测需求都高於单一 Agent。

Mastra 的组件可以让这些层级互相组合，但框架不会自动替你做架构判断。我的建议是从单一 Agent 开始，只有当责任边界、工具集合或上下文真的分裂时，才引入第二个 Agent。很多系统不是模型不够强，而是协作层级太早增加，导致每次错误都要跨越更多不可见状态。

限制与导入前的检查清单

第一，模型差异仍然存在。统一的 model routing 不能抹平不同模型的能力、价格、延迟与安全政策。至少要准备一组自己的任务集，测试工具呼叫成功率、拒答、格式正确性与成本。

第二，Agent 的自主性需要边界。工具的 schema、权限、可存取资料与可执行副作用都要在程式码与基础设施层限制，不要只依赖自然语言指令。尤其是会写资料、寄信、付款或修改设定的工具，应该预设加入 human in the loop 或明确的 approval gate。

第三，可观测不等于可治理。有 trace 只代表你能回看执行过程；你仍要决定哪些资料可以记录、哪些内容必须遮罩、trace 保存多久，以及谁能查看。若系统处理客户资料，这些问题应在第一个 prototype 就纳入设计。

第四，授权模式需要看清楚。Mastra README 说明核心框架与大部分程式码采 Apache License 2.0，但名称为 ee 的目录采 Mastra Enterprise License，正式环境使用相关企业功能需要有效授权。导入前要阅读完整 LICENSE.md，不能因为 repository 是公开的，就假设所有目录与所有使用情境都具有相同授权条件。

第五，不要把 Studio 当成完成品的替代物。Studio 适合开发、测试与理解 Agent 行为；正式产品仍需要自己的身份验证、权限、网路隔离、错误回复、成本控制与部署策略。

我会怎么评估是否采用？

我会把评估分成三个阶段。第一阶段只验证开发体验：能不能在团队熟悉的 TypeScript 专案中建立 Agent、挂一个工具、跑通 Studio，并且让新成员看懂档案边界。第二阶段验证可靠性：加入 workflow、暂停恢复、错误重试、trace 和一组固定 evals，观察结果是否可重现。第三阶段才验证产品条件：模型成本、资料治理、权限、部署方式与授权。

如果团队已经有成熟的 Node 或 TypeScript stack，又确实要做 agents、tool calling、RAG 与工作流协调，Mastra 值得放进短名单。它的优势不是让每个人都能一句 prompt 做出产品，而是把多个常见 AI application patterns 放入一个较完整的工程框架。

反过来说，如果产品只是单一 API 呼叫、团队不需要 workflow 或 observability，直接使用既有 SDK 会更轻量。若团队主要使用另一种语言，也应先评估跨语言服务边界，而不是为了追逐热门工具强行改变整个技术栈。

结语：真正的问题不是能不能建立 Agent，而是能不能长期维护

Mastra 的吸引力，在于它把 AI Agent 从一段 prompt 与 API call，拉回到熟悉的软体工程语境：有模组、有流程、有工具契约、有状态、有评估，也有观测资料。这种转变不会消除 Agent 的不确定性，但能让不确定性被分隔、被测量、被限制。

我会把它推荐给正在从 demo 走向产品的 TypeScript 团队，而不是推荐给只想快速试一次模型的个人开发者。最好的导入方式也不是一次采用全部模组，而是先用一个小型、可验证的 Agent 建立基线，再逐步加入 workflow、memory、human approval、evals 与 observability。当每一个新增能力都有清楚的理由，Mastra 才会成为工程上的杠杆，而不是另一个需要被维护的抽象层。

参考资料