Mastra 入门指南理解 Agent 概念并构建你的第一个 AI Agent【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文是 Mastra 第一个 Agent 课程的开篇核心目标是用最直接的方式让你理解Agent智能体到底是什么以及如何在 Mastra 这个 TypeScript AI 框架中迈出第一步——构建一个能够通过自定义工具读取公开 Google Sheet 数据的简单 Agent。读完本文你将掌握 Agent 的四大核心能力记忆、规划、工具调用、反馈循环了解 Mastra 的项目结构与安装验证方法并亲手完成一个从系统提示词设计到工具创建与挂载的完整 Agent 实战。什么是 Agent在开始写代码之前先建立最基础的概念Agent 是一种运行非确定性代码的软件。与固定、可预测的传统程序不同Agent 能够基于输入和环境做出自主决策。具体来说Agent 是能够完成以下四件事的 AI 系统感知环境通过各种输入渠道感知外部环境做出决策基于这些输入做出判断与决策采取行动执行具体动作以达成特定目标学习与适应随时间推移学习并调整自身行为而一个优秀的 Agent 通常依赖四个关键特性这也是后续课程反复围绕展开的核心主题记忆Memory记住过往交互并从中学到经验规划Planning把复杂任务拆解为更小的步骤工具调用Tool use借助外部工具和 API 扩展自身能力边界反馈循环Feedback loops评估自身表现并据此调整这四个特性正是 Mastra 框架设计的核心出发点。Mastra 的定位是modern TypeScript framework for AI-powered applications and agents为 AI 应用与 Agent 打造的现代 TypeScript 框架它把这些 AI 工程的基础原语开箱即用地打包在一起。在本课程中你会逐一实践工具调用与记忆最终构建出一个具备上述能力的完整 Agent。Mastra构建 Agent 的 TypeScript 框架Mastra 是一个开源的 TypeScript AI Agent 框架开箱即用地提供了 AI 工程所需的全部基础原语包括Agents带工具tools、记忆memory与追踪tracing的智能体Workflows基于状态机的可编排工作流Evals用于跟踪和衡量 AI 输出的评估体系Storage支撑 RAG 流水线的存储方案本地开发 Playground可视化的本地调试与测试环境框架设计上强调模块化与可扩展性——你既可以快速构建、测试、部署能执行多种任务的 AI Agent也可以在需要时按需挂载新能力。本课程聚焦于其中最基础也最核心的部分Agent 与其工具系统。环境准备与安装验证动手前先确认开发环境就绪。首先检查是否安装了Node.js 18.x 或更高版本。然后检查项目中是否已经存在 Mastrapackage.json中是否包含mastra/core依赖是否存在src/mastra目录如果两者都满足说明环境已就绪可直接跳到下一节。如果尚未安装 Mastra运行npm -y create mastralatest按屏幕提示完成初始化时需要注意以下几个选项同时勾选安装 Agents 与 Workflows选择安装 tools工具模型提供商选择 OpenAI、Anthropic 或 Google 三者之一勾选添加示例代码example安装完成后你还需要把所选模型提供商的API Key 配置到项目中例如 OpenAI 的OPENAI_API_KEYAgent 才能实际调用语言模型。理解 Mastra 的项目结构CLI 初始化完成后项目的src/mastra目录遵循一套固定的约定结构src/mastra/ ├── index.ts # Mastra 项目的主入口文件 ├── agents/ # 存放各个 Agent 定义 ├── scorers/ # 存放各个评分器scorer定义 ├── tools/ # 存放各个工具tool定义 └── workflows/ # 存放各个工作流定义如果 CLI 生成了示例项目你会看到对应的示例文件agents/weather-agent.ts—— 示例天气 Agentscorers/weather-scorer.ts—— 示例天气评分器tools/weather-tool.ts—— 示例天气工具workflows/weather-workflow.ts—— 示例天气工作流这套目录结构是 Mastra 组织代码的约定惯例index.ts是项目主入口而agents/、tools/等目录分别承载 Agent 与工具的定义。遵循这套结构后续的 Playground 调试、服务导出都会自动识别你的代码。设计 Agent 的灵魂系统提示词一个优秀 Agent 的基础是系统提示词system prompt。它定义了 Agent 的目的、能力与行为准则直接决定 Agent 与用户交互的方式。一份精心设计的系统提示词应当包含五个部分角色定义Role definitionAgent 是什么、做什么核心能力Core capabilitiesAgent 能执行哪些任务行为准则Behavioral guidelinesAgent 如何回应与交互约束边界ConstraintsAgent 不应做什么或讨论什么成功标准Success criteria怎样的回应才算好系统提示词相当于引导 Agent 行为的一组指令。清晰、全面的提示词会让 Agent 的回复更一致、更有帮助。在 Mastra 中这段提示词会作为instructions配置直接传给 Agent 构造函数见下文实战。实战创建你的第一个 Agent现在动手创建一个帮助用户分析金融交易数据的 Agent。首先在src/mastra/agents/下新建文件financial-agent.ts。在文件顶部添加必要的导入import { Agent } from mastra/core/agent // 工具将在后续步骤中导入然后创建 Agent 实例export const financialAgent new Agent({ name: Financial Assistant Agent, instructions: ROLE DEFINITION - You are a financial assistant that helps users analyze their transaction data. - Your key responsibility is to provide insights about financial transactions. - Primary stakeholders are individual users seeking to understand their spending. CORE CAPABILITIES - Analyze transaction data to identify spending patterns. - Answer questions about specific transactions or vendors. - Provide basic summaries of spending by category or time period. BEHAVIORAL GUIDELINES - Maintain a professional and friendly communication style. - Keep responses concise but informative. - Always clarify if you need more information to answer a question. - Format currency values appropriately. - Ensure user privacy and data security. CONSTRAINTS BOUNDARIES - Do not provide financial investment advice. - Avoid discussing topics outside of the transaction data provided. - Never make assumptions about the users financial situation beyond whats in the data. SUCCESS CRITERIA - Deliver accurate and helpful analysis of transaction data. - Achieve high user satisfaction through clear and helpful responses. - Maintain user trust by ensuring data privacy and security., model: openai/gpt-5.4, tools: {}, // 工具将在后续步骤中添加 })这样我们就创建了一个具备明确角色、能力、行为准则、约束与成功标准的金融助手 Agent。Agent 核心配置参数深度解析上面的示例用到了 Agent 构造函数的三个核心配置。查看核心包源码 AgentConfigBase 定义 可以进一步理解这些参数的内涵nameAgent 的唯一标识名称。instructions指导 Agent 行为的指令。它不限于字符串还可以是字符串数组、系统消息对象、系统消息数组甚至是按请求动态解析的函数DynamicArgument。提示词设计越结构化角色/能力/约束/成功标准Agent 行为越稳定。modelAgent 使用的语言模型。源码注释展示了多种灵活写法魔法字符串model: openai/gpt-4本文示例即此类写法配置对象model: { id: openai/gpt-4, apiKey: process.env.OPENAI_API_KEY }回退数组model: [{ model: openai/gpt-4, maxRetries: 2 }, { model: anthropic/claude-3-opus, maxRetries: 1 }]当主模型失败时自动切换备用模型动态解析函数model: ({ requestContext }) ...可按请求上下文如用户等级 tier动态选择模型toolsAgent 可访问的工具集合同样支持静态对象或动态解析见下一节。maxRetries模型调用失败时的最大重试次数默认值为0。此外AgentConfigBase还定义了memory记忆模块用于存取有状态上下文、durable持久化执行选项、hooks工具调用前后钩子、scorers运行时评估与可观测性配置等进阶配置后续课程会逐一展开。Agent 的能力扩展理解 Tools工具工具Tools是 Agent 可以调用的函数用于执行特定任务。它们把 Agent 的能力延伸到语言模型本身无法触及的外部世界——外部数据源、API、具体业务动作。在 Mastra 中每个工具由四部分组成唯一 IDAgent 引用该工具时的标识符清晰描述说明工具做什么帮助模型判断何时调用输入/输出 Schema定义期望的参数与返回值结构execute 执行函数执行实际工作从源码看createTool工厂函数 接受一个CreateToolOpts配置对象含id、description、inputSchema、outputSchema、execute等字段返回一个完整的Tool实例。值得注意的是inputSchema、outputSchema均为可选运行时会对工具的输入输出做校验源码 validation.ts 承担校验职责保证 Agent 传给工具的参数符合预期、工具返回值符合声明。实战创建读取 Google Sheet 的工具回到我们的金融助手它的核心任务是从公开 Google Sheet 中读取交易数据。在src/mastra/tools/下新建文件get-transactions-tool.ts。添加导入import { createTool } from mastra/core/tools import { z } from zod然后定义工具export const getTransactionsTool createTool({ id: get-transactions, description: Get transaction data from Google Sheets, inputSchema: z.object({}), // 无需输入参数 outputSchema: z.object({ csvData: z.string(), }), execute: async () { return await getTransactions() }, }) const getTransactions async () { // 该 URL 指向一个包含交易数据的公开 Google Sheet const url https://docs.google.com/spreadsheets/d/e/2PACX-1vTQWaCzJAFsF4owWRHQRLo4G0-ERv31c74OOZFnqLiTLaP7NweoiX7IXvzQud2H6bdUPnIqZEA485Ux/pub?gid0singletrueoutputcsv const response await fetch(url) const data await response.text() return { csvData: data, } }这个工具通过fetch拉取公开 Google Sheet 的 CSV 导出数据并原样返回。createTool让定义工具的四要素ID、描述、输入/输出 Schema、执行逻辑一目了然Zod Schema 同时承担了类型推导与运行时校验的双重职责。把工具连接到 Agent工具建好了还需要挂载到 Agent 上才能真正被调用。回到agents/financial-agent.ts第一步导入工具import { getTransactionsTool } from ../tools/get-transactions-tool第二步把工具加入 Agent 配置并同步更新 instructionsexport const financialAgent new Agent({ name: Financial Assistant Agent, instructions: ROLE DEFINITION // ... 原有指令保持不变 ... TOOLS - Use the getTransactions tool to fetch financial transaction data. - Analyze the transaction data to answer user questions about their spending., model: openai/gpt-5.4, tools: { getTransactionsTool }, // 挂载我们的工具 })这里有两点值得强调挂载工具把getTransactionsTool放进tools字段后Agent 在推理时就能看到该工具并在需要访问交易数据时自主决定调用它。更新指令仅仅挂载还不够你需要在instructions中补充工具使用说明何时用、怎么用帮助模型在合适的场景触发工具调用。这正是前面系统提示词一节所强调的提示词是 Agent 行为的基础。下一步让第一个 Agent 真正运转至此你已经完成了一个最小闭环理解了 Agent 的定义——感知、决策、行动、学习以及记忆、规划、工具调用、反馈循环四大特性搭建了 Mastra 环境——验证 Node.js 版本、安装mastra/core、配置 API Key掌握了项目结构——src/mastra下的 agents、tools、workflows 等约定目录设计了高质量系统提示词——角色、能力、准则、约束、成功标准五位一体创建并连接了工具——用createTool定义读取 Google Sheet 的工具并挂载到 Agent。接下来的课程会继续沿着这条主线推进导出 Agent 并在 Playground 中运行测试、系统深入学习 Memory记忆的安装与接入、为 Agent 配置线程会话与语义召回让这个金融助手从能读数据进化到记得住上下文的完整状态。你可以在仓库中查阅对应的课程文件 02-what-is-mastra.md、07-creating-your-agent.md、11-creating-transactions-tool.md 与 12-connecting-tool-to-agent.md按部就班地完成整个第一个 Agent 的学习旅程。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra 入门指南：理解 Agent 概念并构建你的第一个 AI Agent
Mastra 入门指南理解 Agent 概念并构建你的第一个 AI Agent【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文是 Mastra 第一个 Agent 课程的开篇核心目标是用最直接的方式让你理解Agent智能体到底是什么以及如何在 Mastra 这个 TypeScript AI 框架中迈出第一步——构建一个能够通过自定义工具读取公开 Google Sheet 数据的简单 Agent。读完本文你将掌握 Agent 的四大核心能力记忆、规划、工具调用、反馈循环了解 Mastra 的项目结构与安装验证方法并亲手完成一个从系统提示词设计到工具创建与挂载的完整 Agent 实战。什么是 Agent在开始写代码之前先建立最基础的概念Agent 是一种运行非确定性代码的软件。与固定、可预测的传统程序不同Agent 能够基于输入和环境做出自主决策。具体来说Agent 是能够完成以下四件事的 AI 系统感知环境通过各种输入渠道感知外部环境做出决策基于这些输入做出判断与决策采取行动执行具体动作以达成特定目标学习与适应随时间推移学习并调整自身行为而一个优秀的 Agent 通常依赖四个关键特性这也是后续课程反复围绕展开的核心主题记忆Memory记住过往交互并从中学到经验规划Planning把复杂任务拆解为更小的步骤工具调用Tool use借助外部工具和 API 扩展自身能力边界反馈循环Feedback loops评估自身表现并据此调整这四个特性正是 Mastra 框架设计的核心出发点。Mastra 的定位是modern TypeScript framework for AI-powered applications and agents为 AI 应用与 Agent 打造的现代 TypeScript 框架它把这些 AI 工程的基础原语开箱即用地打包在一起。在本课程中你会逐一实践工具调用与记忆最终构建出一个具备上述能力的完整 Agent。Mastra构建 Agent 的 TypeScript 框架Mastra 是一个开源的 TypeScript AI Agent 框架开箱即用地提供了 AI 工程所需的全部基础原语包括Agents带工具tools、记忆memory与追踪tracing的智能体Workflows基于状态机的可编排工作流Evals用于跟踪和衡量 AI 输出的评估体系Storage支撑 RAG 流水线的存储方案本地开发 Playground可视化的本地调试与测试环境框架设计上强调模块化与可扩展性——你既可以快速构建、测试、部署能执行多种任务的 AI Agent也可以在需要时按需挂载新能力。本课程聚焦于其中最基础也最核心的部分Agent 与其工具系统。环境准备与安装验证动手前先确认开发环境就绪。首先检查是否安装了Node.js 18.x 或更高版本。然后检查项目中是否已经存在 Mastrapackage.json中是否包含mastra/core依赖是否存在src/mastra目录如果两者都满足说明环境已就绪可直接跳到下一节。如果尚未安装 Mastra运行npm -y create mastralatest按屏幕提示完成初始化时需要注意以下几个选项同时勾选安装 Agents 与 Workflows选择安装 tools工具模型提供商选择 OpenAI、Anthropic 或 Google 三者之一勾选添加示例代码example安装完成后你还需要把所选模型提供商的API Key 配置到项目中例如 OpenAI 的OPENAI_API_KEYAgent 才能实际调用语言模型。理解 Mastra 的项目结构CLI 初始化完成后项目的src/mastra目录遵循一套固定的约定结构src/mastra/ ├── index.ts # Mastra 项目的主入口文件 ├── agents/ # 存放各个 Agent 定义 ├── scorers/ # 存放各个评分器scorer定义 ├── tools/ # 存放各个工具tool定义 └── workflows/ # 存放各个工作流定义如果 CLI 生成了示例项目你会看到对应的示例文件agents/weather-agent.ts—— 示例天气 Agentscorers/weather-scorer.ts—— 示例天气评分器tools/weather-tool.ts—— 示例天气工具workflows/weather-workflow.ts—— 示例天气工作流这套目录结构是 Mastra 组织代码的约定惯例index.ts是项目主入口而agents/、tools/等目录分别承载 Agent 与工具的定义。遵循这套结构后续的 Playground 调试、服务导出都会自动识别你的代码。设计 Agent 的灵魂系统提示词一个优秀 Agent 的基础是系统提示词system prompt。它定义了 Agent 的目的、能力与行为准则直接决定 Agent 与用户交互的方式。一份精心设计的系统提示词应当包含五个部分角色定义Role definitionAgent 是什么、做什么核心能力Core capabilitiesAgent 能执行哪些任务行为准则Behavioral guidelinesAgent 如何回应与交互约束边界ConstraintsAgent 不应做什么或讨论什么成功标准Success criteria怎样的回应才算好系统提示词相当于引导 Agent 行为的一组指令。清晰、全面的提示词会让 Agent 的回复更一致、更有帮助。在 Mastra 中这段提示词会作为instructions配置直接传给 Agent 构造函数见下文实战。实战创建你的第一个 Agent现在动手创建一个帮助用户分析金融交易数据的 Agent。首先在src/mastra/agents/下新建文件financial-agent.ts。在文件顶部添加必要的导入import { Agent } from mastra/core/agent // 工具将在后续步骤中导入然后创建 Agent 实例export const financialAgent new Agent({ name: Financial Assistant Agent, instructions: ROLE DEFINITION - You are a financial assistant that helps users analyze their transaction data. - Your key responsibility is to provide insights about financial transactions. - Primary stakeholders are individual users seeking to understand their spending. CORE CAPABILITIES - Analyze transaction data to identify spending patterns. - Answer questions about specific transactions or vendors. - Provide basic summaries of spending by category or time period. BEHAVIORAL GUIDELINES - Maintain a professional and friendly communication style. - Keep responses concise but informative. - Always clarify if you need more information to answer a question. - Format currency values appropriately. - Ensure user privacy and data security. CONSTRAINTS BOUNDARIES - Do not provide financial investment advice. - Avoid discussing topics outside of the transaction data provided. - Never make assumptions about the users financial situation beyond whats in the data. SUCCESS CRITERIA - Deliver accurate and helpful analysis of transaction data. - Achieve high user satisfaction through clear and helpful responses. - Maintain user trust by ensuring data privacy and security., model: openai/gpt-5.4, tools: {}, // 工具将在后续步骤中添加 })这样我们就创建了一个具备明确角色、能力、行为准则、约束与成功标准的金融助手 Agent。Agent 核心配置参数深度解析上面的示例用到了 Agent 构造函数的三个核心配置。查看核心包源码 AgentConfigBase 定义 可以进一步理解这些参数的内涵nameAgent 的唯一标识名称。instructions指导 Agent 行为的指令。它不限于字符串还可以是字符串数组、系统消息对象、系统消息数组甚至是按请求动态解析的函数DynamicArgument。提示词设计越结构化角色/能力/约束/成功标准Agent 行为越稳定。modelAgent 使用的语言模型。源码注释展示了多种灵活写法魔法字符串model: openai/gpt-4本文示例即此类写法配置对象model: { id: openai/gpt-4, apiKey: process.env.OPENAI_API_KEY }回退数组model: [{ model: openai/gpt-4, maxRetries: 2 }, { model: anthropic/claude-3-opus, maxRetries: 1 }]当主模型失败时自动切换备用模型动态解析函数model: ({ requestContext }) ...可按请求上下文如用户等级 tier动态选择模型toolsAgent 可访问的工具集合同样支持静态对象或动态解析见下一节。maxRetries模型调用失败时的最大重试次数默认值为0。此外AgentConfigBase还定义了memory记忆模块用于存取有状态上下文、durable持久化执行选项、hooks工具调用前后钩子、scorers运行时评估与可观测性配置等进阶配置后续课程会逐一展开。Agent 的能力扩展理解 Tools工具工具Tools是 Agent 可以调用的函数用于执行特定任务。它们把 Agent 的能力延伸到语言模型本身无法触及的外部世界——外部数据源、API、具体业务动作。在 Mastra 中每个工具由四部分组成唯一 IDAgent 引用该工具时的标识符清晰描述说明工具做什么帮助模型判断何时调用输入/输出 Schema定义期望的参数与返回值结构execute 执行函数执行实际工作从源码看createTool工厂函数 接受一个CreateToolOpts配置对象含id、description、inputSchema、outputSchema、execute等字段返回一个完整的Tool实例。值得注意的是inputSchema、outputSchema均为可选运行时会对工具的输入输出做校验源码 validation.ts 承担校验职责保证 Agent 传给工具的参数符合预期、工具返回值符合声明。实战创建读取 Google Sheet 的工具回到我们的金融助手它的核心任务是从公开 Google Sheet 中读取交易数据。在src/mastra/tools/下新建文件get-transactions-tool.ts。添加导入import { createTool } from mastra/core/tools import { z } from zod然后定义工具export const getTransactionsTool createTool({ id: get-transactions, description: Get transaction data from Google Sheets, inputSchema: z.object({}), // 无需输入参数 outputSchema: z.object({ csvData: z.string(), }), execute: async () { return await getTransactions() }, }) const getTransactions async () { // 该 URL 指向一个包含交易数据的公开 Google Sheet const url https://docs.google.com/spreadsheets/d/e/2PACX-1vTQWaCzJAFsF4owWRHQRLo4G0-ERv31c74OOZFnqLiTLaP7NweoiX7IXvzQud2H6bdUPnIqZEA485Ux/pub?gid0singletrueoutputcsv const response await fetch(url) const data await response.text() return { csvData: data, } }这个工具通过fetch拉取公开 Google Sheet 的 CSV 导出数据并原样返回。createTool让定义工具的四要素ID、描述、输入/输出 Schema、执行逻辑一目了然Zod Schema 同时承担了类型推导与运行时校验的双重职责。把工具连接到 Agent工具建好了还需要挂载到 Agent 上才能真正被调用。回到agents/financial-agent.ts第一步导入工具import { getTransactionsTool } from ../tools/get-transactions-tool第二步把工具加入 Agent 配置并同步更新 instructionsexport const financialAgent new Agent({ name: Financial Assistant Agent, instructions: ROLE DEFINITION // ... 原有指令保持不变 ... TOOLS - Use the getTransactions tool to fetch financial transaction data. - Analyze the transaction data to answer user questions about their spending., model: openai/gpt-5.4, tools: { getTransactionsTool }, // 挂载我们的工具 })这里有两点值得强调挂载工具把getTransactionsTool放进tools字段后Agent 在推理时就能看到该工具并在需要访问交易数据时自主决定调用它。更新指令仅仅挂载还不够你需要在instructions中补充工具使用说明何时用、怎么用帮助模型在合适的场景触发工具调用。这正是前面系统提示词一节所强调的提示词是 Agent 行为的基础。下一步让第一个 Agent 真正运转至此你已经完成了一个最小闭环理解了 Agent 的定义——感知、决策、行动、学习以及记忆、规划、工具调用、反馈循环四大特性搭建了 Mastra 环境——验证 Node.js 版本、安装mastra/core、配置 API Key掌握了项目结构——src/mastra下的 agents、tools、workflows 等约定目录设计了高质量系统提示词——角色、能力、准则、约束、成功标准五位一体创建并连接了工具——用createTool定义读取 Google Sheet 的工具并挂载到 Agent。接下来的课程会继续沿着这条主线推进导出 Agent 并在 Playground 中运行测试、系统深入学习 Memory记忆的安装与接入、为 Agent 配置线程会话与语义召回让这个金融助手从能读数据进化到记得住上下文的完整状态。你可以在仓库中查阅对应的课程文件 02-what-is-mastra.md、07-creating-your-agent.md、11-creating-transactions-tool.md 与 12-connecting-tool-to-agent.md按部就班地完成整个第一个 Agent 的学习旅程。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考