拓冰网站定制 
1. 为什么 TypeScript 开发者需要 Mastra 这类 Agent 框架如果你平时写 React、Next.js 或 Node.js突然要做一个能自己调工具、能多轮推理的 AI Agent第一反应往往是直接调某个模型的 SDK。但真写起来就会发现模型切换要改业务代码、工具调用要自己拼 JSON Schema、多轮上下文要手动维护、工作流分支要写一堆 if-else。Mastra 就是冲着这些痛点来的——它是一个完全围绕 TypeScript 设计的 AI 应用与 Agent 开发框架GitHub 上已经有两万多 Star也是 YC W25 批次的项目。它解决的核心问题是把「模型接入、Agent 构建、工作流编排、上下文管理、可观测性」这几件事收敛到一套 TypeScript API 里。你不需要引入 Python 运行时也不需要为了换个模型把业务逻辑重写一遍。Mastra 通过统一接口接入 40 多个模型提供商业务代码面向 Mastra 的接口编写切换底层模型时只改配置。这篇文章面向的是想在本机快速跑通一个 Agent 的 TypeScript 开发者。我会从项目初始化讲到 Agent 编排再给出 TaoToken 统一 Key/API 通道的config.toml骨架和settings.json配置示例最后用一个真实的 Agent 调用动作验证整条链路。跟着做你可以在本地开发环境里跑通一个能调用工具的 Agent。Mastra 的定位不是替代你的编辑器或框架而是嵌进你现有的前后端应用里也可以作为独立服务器部署。对于已经在用 TypeScript 全栈的团队接入成本很低。2. 前置准备TaoToken 统一 Key 与 API 通道在写 Agent 之前先把模型通道准备好。Mastra 本身不绑定某一家模型它需要一个兼容 OpenAI 接口的 base URL 和 API Key。TaoToken 提供的就是这样一个统一入口一个 Key 走通多个模型base URL 固定业务代码不用为每个模型写不同的适配层。你需要先拿到两样东西一个 API Key在控制台的 API Keys 页面创建确认 base URL 为https://taotoken.net/api。创建 Key 的入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档包含各语言示例和参数说明在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意base URL 只写到/api不要在后面手动拼/v1之类的路径具体路径由 SDK 或 Mastra 的 provider 配置决定。这一点在排障时经常被忽略。拿到 Key 之后建议先不要急着写 Agent而是用一条最简请求确认通道是通的。这一步能帮你把「Key 问题」和「框架问题」分开后面出错时排查范围会小很多。3. 项目初始化与 Mastra 骨架Mastra 提供了一条命令初始化项目npm create mastralatest跟着向导走它会问你项目名、要不要示例 Agent、用哪个包管理器。初始化完成后目录结构大致是这样my-agent/ ├── src/ │ └── mastra/ │ ├── agents/ │ ├── tools/ │ └── index.ts ├── package.json └── tsconfig.jsonsrc/mastra/index.ts是入口负责注册 Agent 和工具。agents/放 Agent 定义tools/放工具定义。这个结构不是强制的但建议先按它来等跑通再调整。安装依赖cd my-agent npm install如果你不想用向导也可以手动装核心包npm install mastra/coreMastra 的核心包是mastra/coreAgent、Workflow、Tool 都从这里导出。模型接入部分Mastra 通过 provider 适配层对接各家接口你只需要在 Agent 定义里指定模型名和连接信息。接下来配置环境变量。在项目根目录建一个.envTAOTOKEN_API_KEY你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api把 Key 放环境变量里不要硬编码进源码。Mastra 读取模型配置时会用到这些值。4. 可复制配置config.toml 骨架与 settings.json 示例Mastra 本身用 TypeScript 配置为主但在一些工具链和本地开发场景里会用到config.toml和settings.json来做统一管理。下面给出可直接复制的骨架。4.1 config.toml 骨架# config.toml [provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [models] default gpt-4o-mini reasoning claude-3-5-sonnet [agent] name demo-agent max_steps 8 temperature 0.3 [observability] enabled true log_level info这里几个字段值得说明base_url固定为 TaoToken 的 API 地址所有模型共用api_key_env指向环境变量名避免明文写 Keymodels.default和models.reasoning可以指向不同模型业务里按需切换max_steps控制 Agent 内部迭代上限防止死循环。4.2 settings.json 示例{ mastra: { provider: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY }, agent: { name: demo-agent, model: gpt-4o-mini, maxSteps: 8 }, tools: { enabled: [calculator, httpFetch] } } }settings.json适合放在项目根目录或.mastra/下作为本地开发的默认配置。它的字段和config.toml有重叠实际项目里选一种即可不要两处都改否则容易出现「改了没生效」的情况。提示如果你在 CI 或容器里跑建议用环境变量覆盖apiKeyEnv指向的值配置文件本身提交到仓库时不要带真实 Key。5. 构建第一个 Agent 与工具配置准备好之后开始写 Agent。先定义一个工具让 Agent 有东西可调。// src/mastra/tools/calculator.ts import { createTool } from mastra/core/tools; import { z } from zod; export const calculator createTool({ id: calculator, description: 计算两个数字的加减乘除, inputSchema: z.object({ a: z.number(), b: z.number(), op: z.enum([, -, *, /]), }), execute: async ({ context }) { const { a, b, op } context; switch (op) { case : return { result: a b }; case -: return { result: a - b }; case *: return { result: a * b }; case /: return { result: b 0 ? 除数不能为0 : a / b }; } }, });工具用createTool定义inputSchema用 zod 描述参数execute是实际逻辑。Mastra 会把 schema 转成模型能理解的工具描述模型决定什么时候调它。接着定义 Agent// src/mastra/agents/demo-agent.ts import { Agent } from mastra/core/agent; import { calculator } from ../tools/calculator; export const demoAgent new Agent({ name: demo-agent, instructions: 你是一个会使用计算器的助手遇到算术问题先调用工具。, model: { provider: openai, name: gpt-4o-mini, url: process.env.TAOTOKEN_BASE_URL, apiKey: process.env.TAOTOKEN_API_KEY, }, tools: { calculator }, });这里model字段里的url和apiKey指向 TaoToken 的通道。Mastra 的 provider 适配层会按 OpenAI 兼容格式发请求所以只要 base URL 和 Key 对模型就能通。最后在入口注册// src/mastra/index.ts import { Mastra } from mastra/core; import { demoAgent } from ./agents/demo-agent; export const mastra new Mastra({ agents: { demoAgent }, });到这里一个最小可用的 Agent 就搭好了。它有一个工具、一段指令、一个模型通道。6. 验证请求一次 Agent 调用与成功结果启动开发服务器npm run devMastra 会起一个本地服务默认端口在终端里会打印出来。然后写一个调用脚本// scripts/run-agent.ts import { mastra } from ../src/mastra; async function main() { const agent mastra.getAgent(demoAgent); const res await agent.generate(帮我算一下 128 乘以 47 等于多少); console.log(res.text); } main();用tsx跑npx tsx scripts/run-agent.ts如果通道和配置都对你会看到类似输出128 乘以 47 等于 6016。这个过程中Agent 内部做了几件事接收问题、判断需要调用calculator工具、生成工具调用参数{a:128, b:47, op:*}、拿到结果6016、再组织成自然语言返回。你可以在终端日志里看到工具调用的记录这就是可观测性模块在起作用。如果想让 Agent 走多轮可以用stream或带历史消息的generateconst res await agent.generate([ { role: user, content: 128 乘以 47 等于多少 }, { role: assistant, content: 等于 6016 }, { role: user, content: 再除以 8 呢 }, ]); console.log(res.text);多轮上下文由 Mastra 的对话历史模块维护你不需要手动拼 messages 数组之外的东西。7. 本篇常见错误排查跑不通的时候按下面顺序排查基本能覆盖大部分情况。报 401 或鉴权失败先确认TAOTOKEN_API_KEY环境变量真的被读到了。可以在脚本里打印process.env.TAOTOKEN_API_KEY的前几位确认。如果用的是.env注意 Mastra 或 tsx 是否自动加载了它必要时用dotenv显式加载。报 404 或路径错误检查 base URL 是不是写成了https://taotoken.net/api/v1之类。正确写法是https://taotoken.net/api多写的路径会导致请求打到不存在的端点。模型名不识别model.name要和通道支持的模型名一致。如果换模型只改这一处不要动url和apiKey。工具没被调用检查instructions里有没有明确引导模型使用工具以及工具的description是否清晰。模型是靠 description 判断何时调用的描述太模糊它就不调。Agent 陷入循环把maxSteps调小比如 5先看它卡在哪一步。常见原因是工具返回格式和模型预期不一致导致模型反复重试。改了配置没生效确认你改的是config.toml还是settings.json两者只保留一处生效来源。同时检查有没有缓存文件重启开发服务器。TypeScript 类型报错确认mastra/core和zod版本匹配createTool的inputSchema必须是 zod schema不能是普通对象。8. 继续深入工作流、MCP 与 Coding PlanAgent 跑通之后下一步通常是把它接进更复杂的流程。Mastra 的工作流引擎用图结构描述任务.then()串行、.branch()条件分支、.parallel()并行还支持 Human in the loop——在任意节点挂起等人工审批执行状态持久化暂停再久都能从断点恢复。这对需要审核的业务场景很实用。MCP Server 支持也值得关注。Mastra 可以把 Agent、工具通过 Model Context Protocol 暴露给外部系统任何支持该协议的客户端都能调用。跨系统协作时这比自定义接口省事。如果你打算长期做编码类或 Agent 类项目可以了解一下 Coding Plan它更适合持续性的开发场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite想直接在网页里对比不同模型的效果可以用模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite控制台里可以管理 Key、查看用量https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite如果你在用 Claude Code 这类工具Anthropic 兼容通道的说明在这里https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite我自己的习惯是本地开发阶段先用最小 Agent 验证通道确认工具调用链路通了再往上叠工作流和记忆模块。这样出问题时排查范围始终可控。 Mastra 框架实战：用 TypeScript 构建 AI Agent 应用与 TaoToken 配置指南
1. 为什么 TypeScript 开发者需要 Mastra 这类 Agent 框架如果你平时写 React、Next.js 或 Node.js突然要做一个能自己调工具、能多轮推理的 AI Agent第一反应往往是直接调某个模型的 SDK。但真写起来就会发现模型切换要改业务代码、工具调用要自己拼 JSON Schema、多轮上下文要手动维护、工作流分支要写一堆 if-else。Mastra 就是冲着这些痛点来的——它是一个完全围绕 TypeScript 设计的 AI 应用与 Agent 开发框架GitHub 上已经有两万多 Star也是 YC W25 批次的项目。它解决的核心问题是把「模型接入、Agent 构建、工作流编排、上下文管理、可观测性」这几件事收敛到一套 TypeScript API 里。你不需要引入 Python 运行时也不需要为了换个模型把业务逻辑重写一遍。Mastra 通过统一接口接入 40 多个模型提供商业务代码面向 Mastra 的接口编写切换底层模型时只改配置。这篇文章面向的是想在本机快速跑通一个 Agent 的 TypeScript 开发者。我会从项目初始化讲到 Agent 编排再给出 TaoToken 统一 Key/API 通道的config.toml骨架和settings.json配置示例最后用一个真实的 Agent 调用动作验证整条链路。跟着做你可以在本地开发环境里跑通一个能调用工具的 Agent。Mastra 的定位不是替代你的编辑器或框架而是嵌进你现有的前后端应用里也可以作为独立服务器部署。对于已经在用 TypeScript 全栈的团队接入成本很低。2. 前置准备TaoToken 统一 Key 与 API 通道在写 Agent 之前先把模型通道准备好。Mastra 本身不绑定某一家模型它需要一个兼容 OpenAI 接口的 base URL 和 API Key。TaoToken 提供的就是这样一个统一入口一个 Key 走通多个模型base URL 固定业务代码不用为每个模型写不同的适配层。你需要先拿到两样东西一个 API Key在控制台的 API Keys 页面创建确认 base URL 为https://taotoken.net/api。创建 Key 的入口在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档包含各语言示例和参数说明在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite注意base URL 只写到/api不要在后面手动拼/v1之类的路径具体路径由 SDK 或 Mastra 的 provider 配置决定。这一点在排障时经常被忽略。拿到 Key 之后建议先不要急着写 Agent而是用一条最简请求确认通道是通的。这一步能帮你把「Key 问题」和「框架问题」分开后面出错时排查范围会小很多。3. 项目初始化与 Mastra 骨架Mastra 提供了一条命令初始化项目npm create mastralatest跟着向导走它会问你项目名、要不要示例 Agent、用哪个包管理器。初始化完成后目录结构大致是这样my-agent/ ├── src/ │ └── mastra/ │ ├── agents/ │ ├── tools/ │ └── index.ts ├── package.json └── tsconfig.jsonsrc/mastra/index.ts是入口负责注册 Agent 和工具。agents/放 Agent 定义tools/放工具定义。这个结构不是强制的但建议先按它来等跑通再调整。安装依赖cd my-agent npm install如果你不想用向导也可以手动装核心包npm install mastra/coreMastra 的核心包是mastra/coreAgent、Workflow、Tool 都从这里导出。模型接入部分Mastra 通过 provider 适配层对接各家接口你只需要在 Agent 定义里指定模型名和连接信息。接下来配置环境变量。在项目根目录建一个.envTAOTOKEN_API_KEY你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api把 Key 放环境变量里不要硬编码进源码。Mastra 读取模型配置时会用到这些值。4. 可复制配置config.toml 骨架与 settings.json 示例Mastra 本身用 TypeScript 配置为主但在一些工具链和本地开发场景里会用到config.toml和settings.json来做统一管理。下面给出可直接复制的骨架。4.1 config.toml 骨架# config.toml [provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [models] default gpt-4o-mini reasoning claude-3-5-sonnet [agent] name demo-agent max_steps 8 temperature 0.3 [observability] enabled true log_level info这里几个字段值得说明base_url固定为 TaoToken 的 API 地址所有模型共用api_key_env指向环境变量名避免明文写 Keymodels.default和models.reasoning可以指向不同模型业务里按需切换max_steps控制 Agent 内部迭代上限防止死循环。4.2 settings.json 示例{ mastra: { provider: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY }, agent: { name: demo-agent, model: gpt-4o-mini, maxSteps: 8 }, tools: { enabled: [calculator, httpFetch] } } }settings.json适合放在项目根目录或.mastra/下作为本地开发的默认配置。它的字段和config.toml有重叠实际项目里选一种即可不要两处都改否则容易出现「改了没生效」的情况。提示如果你在 CI 或容器里跑建议用环境变量覆盖apiKeyEnv指向的值配置文件本身提交到仓库时不要带真实 Key。5. 构建第一个 Agent 与工具配置准备好之后开始写 Agent。先定义一个工具让 Agent 有东西可调。// src/mastra/tools/calculator.ts import { createTool } from mastra/core/tools; import { z } from zod; export const calculator createTool({ id: calculator, description: 计算两个数字的加减乘除, inputSchema: z.object({ a: z.number(), b: z.number(), op: z.enum([, -, *, /]), }), execute: async ({ context }) { const { a, b, op } context; switch (op) { case : return { result: a b }; case -: return { result: a - b }; case *: return { result: a * b }; case /: return { result: b 0 ? 除数不能为0 : a / b }; } }, });工具用createTool定义inputSchema用 zod 描述参数execute是实际逻辑。Mastra 会把 schema 转成模型能理解的工具描述模型决定什么时候调它。接着定义 Agent// src/mastra/agents/demo-agent.ts import { Agent } from mastra/core/agent; import { calculator } from ../tools/calculator; export const demoAgent new Agent({ name: demo-agent, instructions: 你是一个会使用计算器的助手遇到算术问题先调用工具。, model: { provider: openai, name: gpt-4o-mini, url: process.env.TAOTOKEN_BASE_URL, apiKey: process.env.TAOTOKEN_API_KEY, }, tools: { calculator }, });这里model字段里的url和apiKey指向 TaoToken 的通道。Mastra 的 provider 适配层会按 OpenAI 兼容格式发请求所以只要 base URL 和 Key 对模型就能通。最后在入口注册// src/mastra/index.ts import { Mastra } from mastra/core; import { demoAgent } from ./agents/demo-agent; export const mastra new Mastra({ agents: { demoAgent }, });到这里一个最小可用的 Agent 就搭好了。它有一个工具、一段指令、一个模型通道。6. 验证请求一次 Agent 调用与成功结果启动开发服务器npm run devMastra 会起一个本地服务默认端口在终端里会打印出来。然后写一个调用脚本// scripts/run-agent.ts import { mastra } from ../src/mastra; async function main() { const agent mastra.getAgent(demoAgent); const res await agent.generate(帮我算一下 128 乘以 47 等于多少); console.log(res.text); } main();用tsx跑npx tsx scripts/run-agent.ts如果通道和配置都对你会看到类似输出128 乘以 47 等于 6016。这个过程中Agent 内部做了几件事接收问题、判断需要调用calculator工具、生成工具调用参数{a:128, b:47, op:*}、拿到结果6016、再组织成自然语言返回。你可以在终端日志里看到工具调用的记录这就是可观测性模块在起作用。如果想让 Agent 走多轮可以用stream或带历史消息的generateconst res await agent.generate([ { role: user, content: 128 乘以 47 等于多少 }, { role: assistant, content: 等于 6016 }, { role: user, content: 再除以 8 呢 }, ]); console.log(res.text);多轮上下文由 Mastra 的对话历史模块维护你不需要手动拼 messages 数组之外的东西。7. 本篇常见错误排查跑不通的时候按下面顺序排查基本能覆盖大部分情况。报 401 或鉴权失败先确认TAOTOKEN_API_KEY环境变量真的被读到了。可以在脚本里打印process.env.TAOTOKEN_API_KEY的前几位确认。如果用的是.env注意 Mastra 或 tsx 是否自动加载了它必要时用dotenv显式加载。报 404 或路径错误检查 base URL 是不是写成了https://taotoken.net/api/v1之类。正确写法是https://taotoken.net/api多写的路径会导致请求打到不存在的端点。模型名不识别model.name要和通道支持的模型名一致。如果换模型只改这一处不要动url和apiKey。工具没被调用检查instructions里有没有明确引导模型使用工具以及工具的description是否清晰。模型是靠 description 判断何时调用的描述太模糊它就不调。Agent 陷入循环把maxSteps调小比如 5先看它卡在哪一步。常见原因是工具返回格式和模型预期不一致导致模型反复重试。改了配置没生效确认你改的是config.toml还是settings.json两者只保留一处生效来源。同时检查有没有缓存文件重启开发服务器。TypeScript 类型报错确认mastra/core和zod版本匹配createTool的inputSchema必须是 zod schema不能是普通对象。8. 继续深入工作流、MCP 与 Coding PlanAgent 跑通之后下一步通常是把它接进更复杂的流程。Mastra 的工作流引擎用图结构描述任务.then()串行、.branch()条件分支、.parallel()并行还支持 Human in the loop——在任意节点挂起等人工审批执行状态持久化暂停再久都能从断点恢复。这对需要审核的业务场景很实用。MCP Server 支持也值得关注。Mastra 可以把 Agent、工具通过 Model Context Protocol 暴露给外部系统任何支持该协议的客户端都能调用。跨系统协作时这比自定义接口省事。如果你打算长期做编码类或 Agent 类项目可以了解一下 Coding Plan它更适合持续性的开发场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite想直接在网页里对比不同模型的效果可以用模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite控制台里可以管理 Key、查看用量https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite如果你在用 Claude Code 这类工具Anthropic 兼容通道的说明在这里https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite我自己的习惯是本地开发阶段先用最小 Agent 验证通道确认工具调用链路通了再往上叠工作流和记忆模块。这样出问题时排查范围始终可控。