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），仅供参考