Mastra 入門(mén)指南理解 Agent 概念并構(gòu)建你的第一個(gè) AI Agent【免費(fèi)下載鏈接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ma/mastra導(dǎo)讀本文是 Mastra 第一個(gè) Agent 課程的開(kāi)篇核心目標(biāo)是用最直接的方式讓你理解Agent智能體到底是什么以及如何在 Mastra 這個(gè) TypeScript AI 框架中邁出第一步——構(gòu)建一個(gè)能夠通過(guò)自定義工具讀取公開(kāi) Google Sheet 數(shù)據(jù)的簡(jiǎn)單 Agent。讀完本文你將掌握 Agent 的四大核心能力記憶、規(guī)劃、工具調(diào)用、反饋循環(huán)了解 Mastra 的項(xiàng)目結(jié)構(gòu)與安裝驗(yàn)證方法并親手完成一個(gè)從系統(tǒng)提示詞設(shè)計(jì)到工具創(chuàng)建與掛載的完整 Agent 實(shí)戰(zhàn)。什么是 Agent在開(kāi)始寫(xiě)代碼之前先建立最基礎(chǔ)的概念A(yù)gent 是一種運(yùn)行非確定性代碼的軟件。與固定、可預(yù)測(cè)的傳統(tǒng)程序不同Agent 能夠基于輸入和環(huán)境做出自主決策。具體來(lái)說(shuō)Agent 是能夠完成以下四件事的 AI 系統(tǒng)感知環(huán)境通過(guò)各種輸入渠道感知外部環(huán)境做出決策基于這些輸入做出判斷與決策采取行動(dòng)執(zhí)行具體動(dòng)作以達(dá)成特定目標(biāo)學(xué)習(xí)與適應(yīng)隨時(shí)間推移學(xué)習(xí)并調(diào)整自身行為而一個(gè)優(yōu)秀的 Agent 通常依賴(lài)四個(gè)關(guān)鍵特性這也是后續(xù)課程反復(fù)圍繞展開(kāi)的核心主題記憶Memory記住過(guò)往交互并從中學(xué)到經(jīng)驗(yàn)規(guī)劃Planning把復(fù)雜任務(wù)拆解為更小的步驟工具調(diào)用Tool use借助外部工具和 API 擴(kuò)展自身能力邊界反饋循環(huán)Feedback loops評(píng)估自身表現(xiàn)并據(jù)此調(diào)整這四個(gè)特性正是 Mastra 框架設(shè)計(jì)的核心出發(fā)點(diǎn)。Mastra 的定位是modern TypeScript framework for AI-powered applications and agents為 AI 應(yīng)用與 Agent 打造的現(xiàn)代 TypeScript 框架它把這些 AI 工程的基礎(chǔ)原語(yǔ)開(kāi)箱即用地打包在一起。在本課程中你會(huì)逐一實(shí)踐工具調(diào)用與記憶最終構(gòu)建出一個(gè)具備上述能力的完整 Agent。Mastra構(gòu)建 Agent 的 TypeScript 框架Mastra 是一個(gè)開(kāi)源的 TypeScript AI Agent 框架開(kāi)箱即用地提供了 AI 工程所需的全部基礎(chǔ)原語(yǔ)包括Agents帶工具tools、記憶memory與追蹤tracing的智能體Workflows基于狀態(tài)機(jī)的可編排工作流Evals用于跟蹤和衡量 AI 輸出的評(píng)估體系Storage支撐 RAG 流水線的存儲(chǔ)方案本地開(kāi)發(fā) Playground可視化的本地調(diào)試與測(cè)試環(huán)境框架設(shè)計(jì)上強(qiáng)調(diào)模塊化與可擴(kuò)展性——你既可以快速構(gòu)建、測(cè)試、部署能執(zhí)行多種任務(wù)的 AI Agent也可以在需要時(shí)按需掛載新能力。本課程聚焦于其中最基礎(chǔ)也最核心的部分Agent 與其工具系統(tǒng)。環(huán)境準(zhǔn)備與安裝驗(yàn)證動(dòng)手前先確認(rèn)開(kāi)發(fā)環(huán)境就緒。首先檢查是否安裝了Node.js 18.x 或更高版本。然后檢查項(xiàng)目中是否已經(jīng)存在 Mastrapackage.json中是否包含mastra/core依賴(lài)是否存在src/mastra目錄如果兩者都滿足說(shuō)明環(huán)境已就緒可直接跳到下一節(jié)。如果尚未安裝 Mastra運(yùn)行npm -y create mastralatest按屏幕提示完成初始化時(shí)需要注意以下幾個(gè)選項(xiàng)同時(shí)勾選安裝 Agents 與 Workflows選擇安裝 tools工具模型提供商選擇 OpenAI、Anthropic 或 Google 三者之一勾選添加示例代碼example安裝完成后你還需要把所選模型提供商的API Key 配置到項(xiàng)目中例如 OpenAI 的OPENAI_API_KEYAgent 才能實(shí)際調(diào)用語(yǔ)言模型。理解 Mastra 的項(xiàng)目結(jié)構(gòu)CLI 初始化完成后項(xiàng)目的src/mastra目錄遵循一套固定的約定結(jié)構(gòu)src/mastra/ ├── index.ts # Mastra 項(xiàng)目的主入口文件 ├── agents/ # 存放各個(gè) Agent 定義 ├── scorers/ # 存放各個(gè)評(píng)分器scorer定義 ├── tools/ # 存放各個(gè)工具tool定義 └── workflows/ # 存放各個(gè)工作流定義如果 CLI 生成了示例項(xiàng)目你會(huì)看到對(duì)應(yīng)的示例文件agents/weather-agent.ts—— 示例天氣 Agentscorers/weather-scorer.ts—— 示例天氣評(píng)分器tools/weather-tool.ts—— 示例天氣工具workflows/weather-workflow.ts—— 示例天氣工作流這套目錄結(jié)構(gòu)是 Mastra 組織代碼的約定慣例index.ts是項(xiàng)目主入口而agents/、tools/等目錄分別承載 Agent 與工具的定義。遵循這套結(jié)構(gòu)后續(xù)的 Playground 調(diào)試、服務(wù)導(dǎo)出都會(huì)自動(dòng)識(shí)別你的代碼。設(shè)計(jì) Agent 的靈魂系統(tǒng)提示詞一個(gè)優(yōu)秀 Agent 的基礎(chǔ)是系統(tǒng)提示詞system prompt。它定義了 Agent 的目的、能力與行為準(zhǔn)則直接決定 Agent 與用戶交互的方式。一份精心設(shè)計(jì)的系統(tǒng)提示詞應(yīng)當(dāng)包含五個(gè)部分角色定義Role definitionAgent 是什么、做什么核心能力Core capabilitiesAgent 能執(zhí)行哪些任務(wù)行為準(zhǔn)則Behavioral guidelinesAgent 如何回應(yīng)與交互約束邊界ConstraintsAgent 不應(yīng)做什么或討論什么成功標(biāo)準(zhǔn)Success criteria怎樣的回應(yīng)才算好系統(tǒng)提示詞相當(dāng)于引導(dǎo) Agent 行為的一組指令。清晰、全面的提示詞會(huì)讓 Agent 的回復(fù)更一致、更有幫助。在 Mastra 中這段提示詞會(huì)作為instructions配置直接傳給 Agent 構(gòu)造函數(shù)見(jiàn)下文實(shí)戰(zhàn)。實(shí)戰(zhàn)創(chuàng)建你的第一個(gè) Agent現(xiàn)在動(dòng)手創(chuàng)建一個(gè)幫助用戶分析金融交易數(shù)據(jù)的 Agent。首先在src/mastra/agents/下新建文件financial-agent.ts。在文件頂部添加必要的導(dǎo)入import { Agent } from mastra/core/agent // 工具將在后續(xù)步驟中導(dǎo)入然后創(chuàng)建 Agent 實(shí)例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: {}, // 工具將在后續(xù)步驟中添加 })這樣我們就創(chuàng)建了一個(gè)具備明確角色、能力、行為準(zhǔn)則、約束與成功標(biāo)準(zhǔn)的金融助手 Agent。Agent 核心配置參數(shù)深度解析上面的示例用到了 Agent 構(gòu)造函數(shù)的三個(gè)核心配置。查看核心包源碼 AgentConfigBase 定義 可以進(jìn)一步理解這些參數(shù)的內(nèi)涵nameAgent 的唯一標(biāo)識(shí)名稱(chēng)。instructions指導(dǎo) Agent 行為的指令。它不限于字符串還可以是字符串?dāng)?shù)組、系統(tǒng)消息對(duì)象、系統(tǒng)消息數(shù)組甚至是按請(qǐng)求動(dòng)態(tài)解析的函數(shù)DynamicArgument。提示詞設(shè)計(jì)越結(jié)構(gòu)化角色/能力/約束/成功標(biāo)準(zhǔn)Agent 行為越穩(wěn)定。modelAgent 使用的語(yǔ)言模型。源碼注釋展示了多種靈活寫(xiě)法魔法字符串model: openai/gpt-4本文示例即此類(lèi)寫(xiě)法配置對(duì)象model: { id: openai/gpt-4, apiKey: process.env.OPENAI_API_KEY }回退數(shù)組model: [{ model: openai/gpt-4, maxRetries: 2 }, { model: anthropic/claude-3-opus, maxRetries: 1 }]當(dāng)主模型失敗時(shí)自動(dòng)切換備用模型動(dòng)態(tài)解析函數(shù)model: ({ requestContext }) ...可按請(qǐng)求上下文如用戶等級(jí) tier動(dòng)態(tài)選擇模型toolsAgent 可訪問(wèn)的工具集合同樣支持靜態(tài)對(duì)象或動(dòng)態(tài)解析見(jiàn)下一節(jié)。maxRetries模型調(diào)用失敗時(shí)的最大重試次數(shù)默認(rèn)值為0。此外AgentConfigBase還定義了memory記憶模塊用于存取有狀態(tài)上下文、durable持久化執(zhí)行選項(xiàng)、hooks工具調(diào)用前后鉤子、scorers運(yùn)行時(shí)評(píng)估與可觀測(cè)性配置等進(jìn)階配置后續(xù)課程會(huì)逐一展開(kāi)。Agent 的能力擴(kuò)展理解 Tools工具工具Tools是 Agent 可以調(diào)用的函數(shù)用于執(zhí)行特定任務(wù)。它們把 Agent 的能力延伸到語(yǔ)言模型本身無(wú)法觸及的外部世界——外部數(shù)據(jù)源、API、具體業(yè)務(wù)動(dòng)作。在 Mastra 中每個(gè)工具由四部分組成唯一 IDAgent 引用該工具時(shí)的標(biāo)識(shí)符清晰描述說(shuō)明工具做什么幫助模型判斷何時(shí)調(diào)用輸入/輸出 Schema定義期望的參數(shù)與返回值結(jié)構(gòu)execute 執(zhí)行函數(shù)執(zhí)行實(shí)際工作從源碼看createTool工廠函數(shù) 接受一個(gè)CreateToolOpts配置對(duì)象含id、description、inputSchema、outputSchema、execute等字段返回一個(gè)完整的Tool實(shí)例。值得注意的是inputSchema、outputSchema均為可選運(yùn)行時(shí)會(huì)對(duì)工具的輸入輸出做校驗(yàn)源碼 validation.ts 承擔(dān)校驗(yàn)職責(zé)保證 Agent 傳給工具的參數(shù)符合預(yù)期、工具返回值符合聲明。實(shí)戰(zhàn)創(chuàng)建讀取 Google Sheet 的工具回到我們的金融助手它的核心任務(wù)是從公開(kāi) Google Sheet 中讀取交易數(shù)據(jù)。在src/mastra/tools/下新建文件get-transactions-tool.ts。添加導(dǎo)入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({}), // 無(wú)需輸入?yún)?shù) outputSchema: z.object({ csvData: z.string(), }), execute: async () { return await getTransactions() }, }) const getTransactions async () { // 該 URL 指向一個(gè)包含交易數(shù)據(jù)的公開(kāi) 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, } }這個(gè)工具通過(guò)fetch拉取公開(kāi) Google Sheet 的 CSV 導(dǎo)出數(shù)據(jù)并原樣返回。createTool讓定義工具的四要素ID、描述、輸入/輸出 Schema、執(zhí)行邏輯一目了然Zod Schema 同時(shí)承擔(dān)了類(lèi)型推導(dǎo)與運(yùn)行時(shí)校驗(yàn)的雙重職責(zé)。把工具連接到 Agent工具建好了還需要掛載到 Agent 上才能真正被調(diào)用。回到agents/financial-agent.ts第一步導(dǎo)入工具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 }, // 掛載我們的工具 })這里有兩點(diǎn)值得強(qiáng)調(diào)掛載工具把getTransactionsTool放進(jìn)tools字段后Agent 在推理時(shí)就能看到該工具并在需要訪問(wèn)交易數(shù)據(jù)時(shí)自主決定調(diào)用它。更新指令僅僅掛載還不夠你需要在instructions中補(bǔ)充工具使用說(shuō)明何時(shí)用、怎么用幫助模型在合適的場(chǎng)景觸發(fā)工具調(diào)用。這正是前面系統(tǒng)提示詞一節(jié)所強(qiáng)調(diào)的提示詞是 Agent 行為的基礎(chǔ)。下一步讓第一個(gè) Agent 真正運(yùn)轉(zhuǎn)至此你已經(jīng)完成了一個(gè)最小閉環(huán)理解了 Agent 的定義——感知、決策、行動(dòng)、學(xué)習(xí)以及記憶、規(guī)劃、工具調(diào)用、反饋循環(huán)四大特性搭建了 Mastra 環(huán)境——驗(yàn)證 Node.js 版本、安裝mastra/core、配置 API Key掌握了項(xiàng)目結(jié)構(gòu)——src/mastra下的 agents、tools、workflows 等約定目錄設(shè)計(jì)了高質(zhì)量系統(tǒng)提示詞——角色、能力、準(zhǔn)則、約束、成功標(biāo)準(zhǔn)五位一體創(chuàng)建并連接了工具——用createTool定義讀取 Google Sheet 的工具并掛載到 Agent。接下來(lái)的課程會(huì)繼續(xù)沿著這條主線推進(jìn)導(dǎo)出 Agent 并在 Playground 中運(yùn)行測(cè)試、系統(tǒng)深入學(xué)習(xí) Memory記憶的安裝與接入、為 Agent 配置線程會(huì)話與語(yǔ)義召回讓這個(gè)金融助手從能讀數(shù)據(jù)進(jìn)化到記得住上下文的完整狀態(tài)。你可以在倉(cāng)庫(kù)中查閱對(duì)應(yīng)的課程文件 02-what-is-mastra.md、07-creating-your-agent.md、11-creating-transactions-tool.md 與 12-connecting-tool-to-agent.md按部就班地完成整個(gè)第一個(gè) Agent 的學(xué)習(xí)旅程。【免費(fèi)下載鏈接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ma/mastra創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考