尧图网页设计 
Mastra 插件工具开发完整指南从工具定义到生产部署【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra想让 AI 助手能调用天气接口却不知道从哪下手这是接触 Mastra 插件开发时最常见的卡点。本文以天气查询工具为例把工具定义、存储接入、智能体集成到部署的完整链路走一遍看完即可照做。先建立全局认知Mastra 四大核心模块的分工动手前先弄清四块拼图各管什么。可以简单理解成智能体是人工具是手工作流是流程图存储是记忆。模块职责类比什么时候用到智能体 Agent理解用户意图决定调用哪个工具办事的人一切对话式交互工具 Tool单项能力接收参数、执行、返回结果手任何可被调用的功能工作流 Workflow固定多步骤流程支持分支与循环流程图步骤顺序必须确定的场景存储 Storage持久化会话与工具数据串联前三者记忆长对话、需要回溯本文的插件开发主线只涉及三块先把工具定义出来再让存储接住数据最后挂到智能体上完成调用。第一步初始化 Mastra 项目并启动本地服务这一步要达成什么电脑上有一个 Mastra 项目骨架且本地开发服务能一条命令拉起来后续所有验证都能在本地完成。具体怎么做前提是装好 Node.js 和包管理器pnpm 或 npm。然后做两件事用npx create-mastra my-agent-app生成项目进入目录安装依赖运行npx mastra dev它会同时启动 Studio 和本地服务默认 4111 端口如何验证成功浏览器打开 http://localhost:4111能看到 Studio 界面和项目里的智能体列表说明环境就绪。更详细的本地开发说明见官方本地开发文档。第二步三步定义第一个插件工具输入、输出、执行逻辑这一步要达成什么得到一个可独立调用的天气工具——传入城市名返回结构化的天气数据。具体怎么做Mastra 工具由三部分构成输入 schemazod 定义、执行函数、返回结果。最小可运行版本长这样import { createTool } from mastra/core/tools; import { z } from zod; export const weatherTool createTool({ id: get-weather, description: Get current weather for a location, inputSchema: z.object({ location: z.string().describe(City name) }), execute: async ({ location }) getWeather(location), });两个容易忽略的细节inputSchema的每个字段都写上describe()这是模型判断该传什么值的依据声明outputSchema后返回值会被再校验一次结构不对会立刻暴露完整示例含真实 API 调用和错误处理可以参考仓库里的 examples/agent/src/mastra/tools/weather-tool.ts。如何验证成功本地服务运行时直接在终端执行npx mastra api tool execute get-weather {location:北京}能拿到结构化的 JSON 返回即算通过不需要为此专门写测试脚本。第三步接入存储系统让会话与工具数据流动起来这一步要达成什么会话历史、工具调用记录不再随进程关闭而丢失智能体可以记得上一轮说过什么。具体怎么做Mastra 提供 libsql、pg、redis 等多种存储适配器。本地开发最轻量的选择是 LibSQL创建一个 store 实例在new Mastra(...)时挂到storage字段即可。各存储模块在整体架构中的位置可以看这张总览图如何验证成功在 Studio 里和智能体聊两轮后项目目录里会出现mastra.db文件刷新页面会话历史仍在即说明持久化生效。数据量大时还可以按域拆分比如默认存储与可观测性存储各管各的互不干扰。第四步把工具集成进智能体跑通调用闭环这一步要达成什么用户只需问今天天气怎么样智能体自动选择并调用get-weather整理出答案。具体怎么做构造 Agent 时把工具挂到tools字段并在 instructions 里说明何时该调用它import { Agent } from mastra/core/agent; export const weatherAgent new Agent({ id: weather-agent, name: Weather Assistant, instructions: 回答天气问题提到具体城市时调用 get-weather 工具。, model: openai/gpt-4o, tools: { weatherInfo: weatherTool }, });之后把这个 agent 注册进new Mastra({ agents: { weatherAgent } })即可。如何验证成功在 Studio 中选中该智能体问上海天气如何回复里出现工具调用事件、最后给出温度和天气状况说明意图 → 调用 → 回答闭环已经打通。如果还想把工具暴露给 VSCode 等编辑器使用可以通过 MCP 对外提供服务工具开发高频坑常见原因与排查方法问题常见原因解法工具调用失败、拿不到结果execute里外部 API 报错或抛出未捕获异常捕获异常并返回结构化{ error }先排查网络与密钥模型反复传错参数inputSchema字段缺少describe模型只能猜为每个参数写清晰描述枚举值用z.enum()约束响应慢、有明显性能瓶颈工具内多个远程请求串行执行返回结果过大挤占上下文独立请求并行化输出只保留模型需要的字段一条实用建议先给工具桩一个固定返回值把整条链路跑通再替换真实逻辑。出问题时可以快速区分是工具本身的锅还是接入配置的锅。本地部署 vs 云端部署什么时候选哪种维度本地部署mastra dev/mastra build云端部署Mastra Cloud定位调试、验证、Demo生产服务启动速度秒级拉起支持热更新有构建与发布流程可观测性日志在本地Studio 直连内置监控与日志检索成本免费按用量计费数据存放本地文件如mastra.db平台托管一句话选型开发阶段全程用本地需要给他人使用或正式上线时再切到云端不要过早优化部署。小结Mastra 插件开发的核心就是四件事定义工具、接入存储、挂载智能体、验证闭环本文已全部走通。想立刻上手就从终端执行npx mastra dev开始把天气工具亲手跑起来。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra 插件工具开发完整指南：从工具定义到生产部署
Mastra 插件工具开发完整指南从工具定义到生产部署【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra想让 AI 助手能调用天气接口却不知道从哪下手这是接触 Mastra 插件开发时最常见的卡点。本文以天气查询工具为例把工具定义、存储接入、智能体集成到部署的完整链路走一遍看完即可照做。先建立全局认知Mastra 四大核心模块的分工动手前先弄清四块拼图各管什么。可以简单理解成智能体是人工具是手工作流是流程图存储是记忆。模块职责类比什么时候用到智能体 Agent理解用户意图决定调用哪个工具办事的人一切对话式交互工具 Tool单项能力接收参数、执行、返回结果手任何可被调用的功能工作流 Workflow固定多步骤流程支持分支与循环流程图步骤顺序必须确定的场景存储 Storage持久化会话与工具数据串联前三者记忆长对话、需要回溯本文的插件开发主线只涉及三块先把工具定义出来再让存储接住数据最后挂到智能体上完成调用。第一步初始化 Mastra 项目并启动本地服务这一步要达成什么电脑上有一个 Mastra 项目骨架且本地开发服务能一条命令拉起来后续所有验证都能在本地完成。具体怎么做前提是装好 Node.js 和包管理器pnpm 或 npm。然后做两件事用npx create-mastra my-agent-app生成项目进入目录安装依赖运行npx mastra dev它会同时启动 Studio 和本地服务默认 4111 端口如何验证成功浏览器打开 http://localhost:4111能看到 Studio 界面和项目里的智能体列表说明环境就绪。更详细的本地开发说明见官方本地开发文档。第二步三步定义第一个插件工具输入、输出、执行逻辑这一步要达成什么得到一个可独立调用的天气工具——传入城市名返回结构化的天气数据。具体怎么做Mastra 工具由三部分构成输入 schemazod 定义、执行函数、返回结果。最小可运行版本长这样import { createTool } from mastra/core/tools; import { z } from zod; export const weatherTool createTool({ id: get-weather, description: Get current weather for a location, inputSchema: z.object({ location: z.string().describe(City name) }), execute: async ({ location }) getWeather(location), });两个容易忽略的细节inputSchema的每个字段都写上describe()这是模型判断该传什么值的依据声明outputSchema后返回值会被再校验一次结构不对会立刻暴露完整示例含真实 API 调用和错误处理可以参考仓库里的 examples/agent/src/mastra/tools/weather-tool.ts。如何验证成功本地服务运行时直接在终端执行npx mastra api tool execute get-weather {location:北京}能拿到结构化的 JSON 返回即算通过不需要为此专门写测试脚本。第三步接入存储系统让会话与工具数据流动起来这一步要达成什么会话历史、工具调用记录不再随进程关闭而丢失智能体可以记得上一轮说过什么。具体怎么做Mastra 提供 libsql、pg、redis 等多种存储适配器。本地开发最轻量的选择是 LibSQL创建一个 store 实例在new Mastra(...)时挂到storage字段即可。各存储模块在整体架构中的位置可以看这张总览图如何验证成功在 Studio 里和智能体聊两轮后项目目录里会出现mastra.db文件刷新页面会话历史仍在即说明持久化生效。数据量大时还可以按域拆分比如默认存储与可观测性存储各管各的互不干扰。第四步把工具集成进智能体跑通调用闭环这一步要达成什么用户只需问今天天气怎么样智能体自动选择并调用get-weather整理出答案。具体怎么做构造 Agent 时把工具挂到tools字段并在 instructions 里说明何时该调用它import { Agent } from mastra/core/agent; export const weatherAgent new Agent({ id: weather-agent, name: Weather Assistant, instructions: 回答天气问题提到具体城市时调用 get-weather 工具。, model: openai/gpt-4o, tools: { weatherInfo: weatherTool }, });之后把这个 agent 注册进new Mastra({ agents: { weatherAgent } })即可。如何验证成功在 Studio 中选中该智能体问上海天气如何回复里出现工具调用事件、最后给出温度和天气状况说明意图 → 调用 → 回答闭环已经打通。如果还想把工具暴露给 VSCode 等编辑器使用可以通过 MCP 对外提供服务工具开发高频坑常见原因与排查方法问题常见原因解法工具调用失败、拿不到结果execute里外部 API 报错或抛出未捕获异常捕获异常并返回结构化{ error }先排查网络与密钥模型反复传错参数inputSchema字段缺少describe模型只能猜为每个参数写清晰描述枚举值用z.enum()约束响应慢、有明显性能瓶颈工具内多个远程请求串行执行返回结果过大挤占上下文独立请求并行化输出只保留模型需要的字段一条实用建议先给工具桩一个固定返回值把整条链路跑通再替换真实逻辑。出问题时可以快速区分是工具本身的锅还是接入配置的锅。本地部署 vs 云端部署什么时候选哪种维度本地部署mastra dev/mastra build云端部署Mastra Cloud定位调试、验证、Demo生产服务启动速度秒级拉起支持热更新有构建与发布流程可观测性日志在本地Studio 直连内置监控与日志检索成本免费按用量计费数据存放本地文件如mastra.db平台托管一句话选型开发阶段全程用本地需要给他人使用或正式上线时再切到云端不要过早优化部署。小结Mastra 插件开发的核心就是四件事定义工具、接入存储、挂载智能体、验证闭环本文已全部走通。想立刻上手就从终端执行npx mastra dev开始把天气工具亲手跑起来。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考