Mastra 實戰從零創建你的第一個金融分析 Agentfinancial-agent.ts 完整指南【免費下載鏈接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.項目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇指南承接 Mastra 官方入門課程第一個 Agent章節圍繞創建agents/financial-agent.ts這一核心任務展開你將學會用mastra/core/agent導出的Agent類實例化一個職責清晰的金融交易數據分析助手掌握系統提示詞instructions的結構化編寫方法并通過Mastra實例將其注冊到 Studio 中進行驗證。讀完本文你將具備在 Mastra 項目中獨立創建、導出并調試第一個 Agent 的完整能力。一、前置準備在哪個目錄、用什么結構創建 Agent在動手寫代碼前先確認你的 Mastra 項目已經完成初始化安裝與腳手架驗證參見課程前序章節 01-introduction-to-mastra.md 與 03-verifying-installation.md。本課創建的新文件路徑為src/mastra/agents/financial-agent.tsMastra 的項目結構約定中Agent 文件統一放在src/mastra/agents/目錄下每個 Agent 一個文件、導出獨立的實例這與課程 04-project-structure.md 介紹的目錄組織保持一致。這樣組織的好處是每個 Agent 可以獨立被測試、獨立被復用也能被后續課程中的 memory、tools 等能力模塊按文件粒度組合。二、最小骨架導入Agent并實例化在src/mastra/agents/financial-agent.ts頂部添加導入語句import { Agent } from mastra/core/agent // Well import our tool in a later step注意這里的導入路徑是mastra/core/agent子路徑導出而非籠統的mastra/core。從源碼結構看Agent類是 Mastra 核心包中通過packages/core/src/agent/agent.ts定義并對外導出的核心類課程示例使用子路徑導入可以顯著縮小打包體積并加快冷啟動。隨后創建 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: {}, // Well add tools in a later step })這段代碼創建了一個金融助理 Agent其核心要點如下配置項本課取值作用nameFinancial Assistant AgentAgent 的展示名稱會在 Studio 界面與日志中顯示instructions多段式系統提示詞定義角色、能力、行為準則、約束與成功標準直接塑造模型行為modelopenai/gpt-5.4指定底層大模型格式為提供商/模型名tools{}當前為空對象后續課程會接入交易查詢工具從源碼實現看packages/core/src/agent/agent.tsAgent類的構造函數接收一個AgentConfig類型的配置對象類型定義見 packages/core/src/agent/types.ts構造時會把這些字段解析為內部狀態例如name、model、tools、instructions等都會被逐一保存并參與后續的請求執行。這意味著name、instructions、model、tools并非演示字段而是驅動 Agent 運行的真實配置入口。三、instructions 的結構化寫法為什么這樣組織系統提示詞本課的系統提示詞不是一句話而是按五個板塊組織的一段長文本。這套結構與課程前章 06-understanding-system-prompts.md 提出的系統提示詞設計原則一一對應ROLE DEFINITION角色定義說明 Agent 是誰、服務對象是誰——幫助用戶分析交易數據的金融助手利益相關方是想了解自己消費情況的個人用戶。角色定義越明確模型越不容易越界或答非所問。CORE CAPABILITIES核心能力列出它能做什么——分析消費模式、回答關于具體交易或商戶的問題、按類別或時間段匯總支出。能力清單是模型調用工具、組織回答的行為邊界。BEHAVIORAL GUIDELINES行為準則規定怎么說——專業友好、簡潔但信息充分、信息不足時主動澄清、金額格式化、保護隱私。這決定了交互體驗的一致性。CONSTRAINTS BOUNDARIES約束與邊界明確不能做什么——不提供投資建議、不討論交易數據之外的話題、不做數據之外的假設。約束條款是金融類 Agent 控制合規風險的關鍵。SUCCESS CRITERIA成功標準定義什么樣的回答算好——分析準確、用戶滿意度高、信任與隱私雙保障。在實際工程中系統提示詞往往就是 Agent 產品需求文檔的濃縮版把產品定位、功能范圍、話術風格、紅線約束寫清楚模型的行為就會顯著更穩定。后續課程會把這份 instructions 與自定義工具、memory 組合讓 Agent 從會說話升級為能辦事。四、model 字段說明格式、生效前提與注意事項model: openai/gpt-5.4采用了 Mastra 的provider/model字符串格式。需要特別注意以下前提與限制必須安裝對應 provider 包使用openai/前綴需要項目中安裝并配置好對應的 OpenAI provider 依賴及 API Key模型字符串才能被正確解析與調用。如果尚未配置Agent 仍可創建但實際生成回答時會因缺少憑據而失敗。模型名以當前可用模型為準gpt-5.4是課程編寫時采用的示例模型名。真實部署時請以你所安裝的 provider 版本實際支持、且你賬戶有權限訪問的模型為準替換字符串即可其余代碼無需改動。運行時與類型系統雙支持從Agent類實現看packages/core/src/agent/agent.tsmodel字段既可以是單個模型配置字符串也支持傳入帶重試的模型數組ModelWithRetries[]為生產環境的模型降級與容錯預留了空間。五、tools 占位為下一步接工具留好接口代碼中tools: {}是一個顯式的空對象占位。在 Mastra 中tools是 Agent 能力擴展的核心掛載點——Agent 通過工具感知外部世界并執行動作查詢數據庫、調用 API、讀寫文件等。當前階段留空是刻意為之課程 07-creating-your-agent.md 只負責造出 Agent 本體后續章節10-understanding-tools.md、11-creating-transactions-tool.md會創建交易查詢工具并在 12-connecting-tool-to-agent.md 中把工具掛回這個對象。所以這里先保持空對象讓本課代碼可運行、可測試同時為后續演進留出清晰接口。六、導出 Agent接入 Mastra 實例才能在 Studio 中使用僅創建文件還不夠要讓 Agent 出現在 StudioPlayground中必須通過Mastra類注冊。修改src/mastra/index.tsimport { Mastra } from mastra/core import { PinoLogger } from mastra/loggers import { LibSQLStore } from mastra/libsql import { financialAgent } from ./agents/financial-agent export const mastra new Mastra({ agents: { financialAgent, }, storage: new LibSQLStore({ id: learning-memory-storage, url: :memory:, }), logger: new PinoLogger({ name: Mastra, level: info, }), })這段注冊代碼完整講解見課程 08-exporting-your-agent.md做了三件事注冊 Agent通過agents字段把financialAgent掛到 Mastra 實例上這是 Studio 能發現它的前提配置存儲LibSQLStore使用內存地址:memory:開發階段無需任何數據庫服務即可運行會話與消息落庫后自動清空配置日志PinoLogger以info級別輸出運行日志便于調試與觀測。從源碼結構看Mastra類是 Mastra 項目的總入口main entry point負責注冊 agents 并統一裝配 storage、logger 等核心服務Agent 實例在注冊后會獲得運行所需的完整上下文。七、運行驗證在 Studio 中與 Agent 對話完成注冊后啟動開發服務npm run dev服務啟動后打開http://localhost:4111即可進入 Mastra Studio詳見課程 05-running-playground.md。你可以在界面中向financialAgent發送消息驗證角色定義與行為準則是否生效例如要求總結我的消費模式觀察回答是否符合 CORE CAPABILITIES 的邊界查看 Agent 的思考過程與內部執行軌跡定位提示詞中哪些條款在起作用在后續課程接入工具后直接在 Studio 中測試工具調用。需要提醒的是當前階段尚未接入交易數據工具Agent 還只能基于提示詞進行通用型回答要讓它真正分析交易數據請繼續完成課程 11-creating-transactions-tool.md 起的工具創建與連接步驟。八、小結與下一步至此你已完成第一個 Mastra Agent 的創建在src/mastra/agents/financial-agent.ts中通過mastra/core/agent導入并實例化Agent用角色定義 / 核心能力 / 行為準則 / 約束邊界 / 成功標準五段式編寫了金融分析場景的系統提示詞指定了model與空的tools占位通過Mastra實例注冊 Agent并在 Studiolocalhost:4111中完成運行驗證。后續課程將依次為你接入交易數據查詢工具11-creating-transactions-tool.md、12-connecting-tool-to-agent.md、記憶能力15-installing-memory.md、16-adding-memory-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（financial-agent.ts 完整指南）
Mastra 實戰從零創建你的第一個金融分析 Agentfinancial-agent.ts 完整指南【免費下載鏈接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.項目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇指南承接 Mastra 官方入門課程第一個 Agent章節圍繞創建agents/financial-agent.ts這一核心任務展開你將學會用mastra/core/agent導出的Agent類實例化一個職責清晰的金融交易數據分析助手掌握系統提示詞instructions的結構化編寫方法并通過Mastra實例將其注冊到 Studio 中進行驗證。讀完本文你將具備在 Mastra 項目中獨立創建、導出并調試第一個 Agent 的完整能力。一、前置準備在哪個目錄、用什么結構創建 Agent在動手寫代碼前先確認你的 Mastra 項目已經完成初始化安裝與腳手架驗證參見課程前序章節 01-introduction-to-mastra.md 與 03-verifying-installation.md。本課創建的新文件路徑為src/mastra/agents/financial-agent.tsMastra 的項目結構約定中Agent 文件統一放在src/mastra/agents/目錄下每個 Agent 一個文件、導出獨立的實例這與課程 04-project-structure.md 介紹的目錄組織保持一致。這樣組織的好處是每個 Agent 可以獨立被測試、獨立被復用也能被后續課程中的 memory、tools 等能力模塊按文件粒度組合。二、最小骨架導入Agent并實例化在src/mastra/agents/financial-agent.ts頂部添加導入語句import { Agent } from mastra/core/agent // Well import our tool in a later step注意這里的導入路徑是mastra/core/agent子路徑導出而非籠統的mastra/core。從源碼結構看Agent類是 Mastra 核心包中通過packages/core/src/agent/agent.ts定義并對外導出的核心類課程示例使用子路徑導入可以顯著縮小打包體積并加快冷啟動。隨后創建 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: {}, // Well add tools in a later step })這段代碼創建了一個金融助理 Agent其核心要點如下配置項本課取值作用nameFinancial Assistant AgentAgent 的展示名稱會在 Studio 界面與日志中顯示instructions多段式系統提示詞定義角色、能力、行為準則、約束與成功標準直接塑造模型行為modelopenai/gpt-5.4指定底層大模型格式為提供商/模型名tools{}當前為空對象后續課程會接入交易查詢工具從源碼實現看packages/core/src/agent/agent.tsAgent類的構造函數接收一個AgentConfig類型的配置對象類型定義見 packages/core/src/agent/types.ts構造時會把這些字段解析為內部狀態例如name、model、tools、instructions等都會被逐一保存并參與后續的請求執行。這意味著name、instructions、model、tools并非演示字段而是驅動 Agent 運行的真實配置入口。三、instructions 的結構化寫法為什么這樣組織系統提示詞本課的系統提示詞不是一句話而是按五個板塊組織的一段長文本。這套結構與課程前章 06-understanding-system-prompts.md 提出的系統提示詞設計原則一一對應ROLE DEFINITION角色定義說明 Agent 是誰、服務對象是誰——幫助用戶分析交易數據的金融助手利益相關方是想了解自己消費情況的個人用戶。角色定義越明確模型越不容易越界或答非所問。CORE CAPABILITIES核心能力列出它能做什么——分析消費模式、回答關于具體交易或商戶的問題、按類別或時間段匯總支出。能力清單是模型調用工具、組織回答的行為邊界。BEHAVIORAL GUIDELINES行為準則規定怎么說——專業友好、簡潔但信息充分、信息不足時主動澄清、金額格式化、保護隱私。這決定了交互體驗的一致性。CONSTRAINTS BOUNDARIES約束與邊界明確不能做什么——不提供投資建議、不討論交易數據之外的話題、不做數據之外的假設。約束條款是金融類 Agent 控制合規風險的關鍵。SUCCESS CRITERIA成功標準定義什么樣的回答算好——分析準確、用戶滿意度高、信任與隱私雙保障。在實際工程中系統提示詞往往就是 Agent 產品需求文檔的濃縮版把產品定位、功能范圍、話術風格、紅線約束寫清楚模型的行為就會顯著更穩定。后續課程會把這份 instructions 與自定義工具、memory 組合讓 Agent 從會說話升級為能辦事。四、model 字段說明格式、生效前提與注意事項model: openai/gpt-5.4采用了 Mastra 的provider/model字符串格式。需要特別注意以下前提與限制必須安裝對應 provider 包使用openai/前綴需要項目中安裝并配置好對應的 OpenAI provider 依賴及 API Key模型字符串才能被正確解析與調用。如果尚未配置Agent 仍可創建但實際生成回答時會因缺少憑據而失敗。模型名以當前可用模型為準gpt-5.4是課程編寫時采用的示例模型名。真實部署時請以你所安裝的 provider 版本實際支持、且你賬戶有權限訪問的模型為準替換字符串即可其余代碼無需改動。運行時與類型系統雙支持從Agent類實現看packages/core/src/agent/agent.tsmodel字段既可以是單個模型配置字符串也支持傳入帶重試的模型數組ModelWithRetries[]為生產環境的模型降級與容錯預留了空間。五、tools 占位為下一步接工具留好接口代碼中tools: {}是一個顯式的空對象占位。在 Mastra 中tools是 Agent 能力擴展的核心掛載點——Agent 通過工具感知外部世界并執行動作查詢數據庫、調用 API、讀寫文件等。當前階段留空是刻意為之課程 07-creating-your-agent.md 只負責造出 Agent 本體后續章節10-understanding-tools.md、11-creating-transactions-tool.md會創建交易查詢工具并在 12-connecting-tool-to-agent.md 中把工具掛回這個對象。所以這里先保持空對象讓本課代碼可運行、可測試同時為后續演進留出清晰接口。六、導出 Agent接入 Mastra 實例才能在 Studio 中使用僅創建文件還不夠要讓 Agent 出現在 StudioPlayground中必須通過Mastra類注冊。修改src/mastra/index.tsimport { Mastra } from mastra/core import { PinoLogger } from mastra/loggers import { LibSQLStore } from mastra/libsql import { financialAgent } from ./agents/financial-agent export const mastra new Mastra({ agents: { financialAgent, }, storage: new LibSQLStore({ id: learning-memory-storage, url: :memory:, }), logger: new PinoLogger({ name: Mastra, level: info, }), })這段注冊代碼完整講解見課程 08-exporting-your-agent.md做了三件事注冊 Agent通過agents字段把financialAgent掛到 Mastra 實例上這是 Studio 能發現它的前提配置存儲LibSQLStore使用內存地址:memory:開發階段無需任何數據庫服務即可運行會話與消息落庫后自動清空配置日志PinoLogger以info級別輸出運行日志便于調試與觀測。從源碼結構看Mastra類是 Mastra 項目的總入口main entry point負責注冊 agents 并統一裝配 storage、logger 等核心服務Agent 實例在注冊后會獲得運行所需的完整上下文。七、運行驗證在 Studio 中與 Agent 對話完成注冊后啟動開發服務npm run dev服務啟動后打開http://localhost:4111即可進入 Mastra Studio詳見課程 05-running-playground.md。你可以在界面中向financialAgent發送消息驗證角色定義與行為準則是否生效例如要求總結我的消費模式觀察回答是否符合 CORE CAPABILITIES 的邊界查看 Agent 的思考過程與內部執行軌跡定位提示詞中哪些條款在起作用在后續課程接入工具后直接在 Studio 中測試工具調用。需要提醒的是當前階段尚未接入交易數據工具Agent 還只能基于提示詞進行通用型回答要讓它真正分析交易數據請繼續完成課程 11-creating-transactions-tool.md 起的工具創建與連接步驟。八、小結與下一步至此你已完成第一個 Mastra Agent 的創建在src/mastra/agents/financial-agent.ts中通過mastra/core/agent導入并實例化Agent用角色定義 / 核心能力 / 行為準則 / 約束邊界 / 成功標準五段式編寫了金融分析場景的系統提示詞指定了model與空的tools占位通過Mastra實例注冊 Agent并在 Studiolocalhost:4111中完成運行驗證。后續課程將依次為你接入交易數據查詢工具11-creating-transactions-tool.md、12-connecting-tool-to-agent.md、記憶能力15-installing-memory.md、16-adding-memory-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），僅供參考