系列文章写到这里，我们从 LLM 的原理一路聊到了 Agent、Workflow、MCP。前面几篇一直在讲概念——什么是 Agent Loop、什么是 Plan-Execute-Observe、什么是 RAG 的 Chunk 和 Embedding。

但这些概念最终要落地到代码里。对于 TypeScript 开发者来说，问题从来不是“这些概念我懂不懂”，而是“从零撸一个带记忆、带 RAG、带 Tool Calling 的 Agent 系统，代码量和工作量有多大”。

Mastra 就是来解决这个问题的。

Mastra 是什么？

简单说，Mastra 是一个开源的 TypeScript AI Agent 框架。它把自己定位成“AI Runtime + Agent Framework”——不只是帮你调个 LLM API，而是把 Agent、Workflow、RAG、Memory、MCP、可观测性这些你在生产环境需要的东西，全部封装好，用一套 TypeScript 原生 API 暴露给你。

官网是https://mastra.ai/ ，Apache 2.0 开源协议，你可以放心用在商业项目里。

用我们系列文章的“超级毕业生”比喻来理解：前面几篇我们一直在教你怎么指挥这个毕业生干活——怎么给他写员工手册（System Prompt）、怎么给他配工具（Tools）、怎么让他查资料库（RAG）、怎么让他记住事情（Memory）、怎么让他自己一步步推任务（Agent Loop）。Mastra 相当于给你一整套现成的“毕业生管理平台”——你不用自己造轮子了，直接在框架里定义 Agent、注册工具、配置记忆、搭 Workflow 就行。

基本使用

安装

pnpm create mastra

创建项目完成后，你大概可以得到这样的一个目录：

目录看完了，我们分析一下核心入口文件：server/src/mastra/index.ts。为其加上注释后，整体变得更简单了。当然这里有一些是我后面安装的插件。反正这个文件，大概就是做了一些操作：

• 可以配置服务端信息
• 注册工作流
• 注册智能体
• 注册评分器
• 配置存储
• 配置日志
• 配置可观察性

import { Mastra } from '@mastra/core/mastra';
import { PinoLogger } from '@mastra/loggers';
import { LibSQLStore } from '@mastra/libsql';
import { DuckDBStore } from "@mastra/duckdb";
import { MastraEditor } from '@mastra/editor';
import { MastraCompositeStore } from '@mastra/core/storage';
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter
} from '@mastra/observability';

import { weatherWorkflow } from './workflows/weather-workflow';
import { weatherAgent } from './agents/weather-agent';
import { toolCallAppropriatenessScorer, completenessScorer, translationScorer } from './scorers/weather-scorer';

import { baseAgent } from './agents/base-agent';

export const mastra = new Mastra({
  // 服务器配置
  server: {
    port: 3000,
    // host: '0.0.0.0',
  },
  // 编辑器
  editor: new MastraEditor(),
  // 工作流
  workflows: {
    weatherWorkflow
  },
  // 智能体
  agents: {
    weatherAgent,
    baseAgent,
  },
  // 评分器
  scorers: {
    toolCallAppropriatenessScorer,
    completenessScorer,
    translationScorer
  },
  // 复合存储：主数据 LibSQL；observability 域使用 DuckDB（异步初始化）
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    // 默认存储使用本地 LibSQL
    default: new LibSQLStore({
      id: "mastra-storage",
      url: "file:./mastra.db",
    }),
    // 可观测性事件单独写入 DuckDB 域
    domains: {
      observability: await new DuckDBStore().getStore('observability'),
    }
  }),
  // 日志配置
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
  // 配置可观察性
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(), // 将可观测性事件持久化到 Mastra 存储
          new MastraPlatformExporter(), // 若设置了 MASTRA_PLATFORM_ACCESS_TOKEN，则上报到 Mastra 平台
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // 对密码、令牌、密钥等敏感字段做脱敏
        ],
      },
    },
  }),
});

下载 Ollama

Agent 做任何事情都要使用 LLM 模型。这里我们使用免费的模型，去 Ollama 中下载免费的模型。不过这里我们需要先下载 Ollama。

这里是一个使用教程：https://meishanlaoyao.blog.csdn.net/article/details/145559813

添加模型

下载模型后，我从 Ollama 中下载了一个 qwen3:8b（需要魔法下载得更快），如果电脑资源有限，可以下载体积更小的。
然后需要连接 Ollama 的 SDK。

pnpm add ollama-ai-provider-v2

然后我们去 server/src/mastra/models 下，创建一个 ollama.model.ts，在里面写入：

import { createOllama } from 'ollama-ai-provider-v2';

const ollama = createOllama({
    baseURL: 'http://localhost:11434/api'
});

export const qwen3_8b = ollama('qwen3:8b');

添加新 Agent

在 server/src/mastra/agents 随便创建一个 agent。

// server\src\mastra\agents\base-agent.ts
import { Agent } from '@mastra/core/agent';
import { Memory } from '@mastra/memory';
import { qwen3_8b } from '../models/ollama.model';

export const baseAgent = new Agent({
    id: 'base-agent',
    name: '基础智能体',
    instructions: '你是一个基础的智能体，能够执行简单的任务。',
    model: qwen3_8b,
    memory: new Memory(), // 内存管理，用于保存对话历史
});

然后在 server/src/mastra/index.ts 中引入并配置进去：

import { baseAgent } from './agents/base-agent';

export const mastra = new Mastra({
  // 智能体
  agents: {
    baseAgent,
  },
});

启动项目

在终端输入：

pnpm dev

然后访问