在 Mastra 中通过 Agent Instructions 教会 AI 何时使用 Zapier MCP 工具

在 Mastra 中通过 Agent Instructions 教会 AI 何时使用 Zapier MCP 工具【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本篇文章聚焦 Mastra 框架中一个看似简单却决定 Agent 行为质量的关键环节如何通过更新 Agent 的instructions系统提示词让 AI 准确理解并使用 Zapier MCP 提供的 Gmail、社交媒体等外部工具。文中以 Zapier MCP 集成课程 中的实战步骤为核心结合 Mastra 源码对instructions的处理机制讲透指令如何影响工具调用决策读完后你将掌握一套可直接复制的 Agent 指令编写范式以及从 MCP 配置、工具初始化到指令注入的完整链路。1. 这一步在课程中的位置为什么轮到更新指令在 02-agent-tools-mcp 课程目录 中Zapier 集成的完整步骤依次为认识 MCP 是什么安装并配置 MCP 客户端在src/mastra/agents/index.ts中写入 Zapier 服务器配置初始化mcpTools await mcp.listTools()把mcpTools展开进 Agent 的tools属性更新 Agent 的 instructions本文在 playground 中实测 Zapier 调用也就是说到这一步时 Agent已经拥有了 Zapier 工具的能力配置、连接、注册都已完成但 Agent 还不知道这些工具是干什么的、什么时候该用。更新 instructions 正是解决模型层面如何决策的问题。前置知识Zapier MCP 服务器需要两个凭证——MCP Server URL和API Key前者是 Agent 的连接端点后者以Bearer {apiKey}形式随每次请求发送以验证身份详见 What is Zapier MCP。2. 核心示例把 Zapier 工具能力写进 Agent 指令本步骤对 Agent 的修改集中在src/mastra/agents/index.ts中的personalAssistantAgent定义上完整代码如下export const personalAssistantAgent new Agent({ name: Personal Assistant, instructions: You are a helpful personal assistant that can help with various tasks such as email and scheduling social media posts. You have access to the following tools: 1. Gmail: - Use these tools for reading and categorizing emails from Gmail - You can categorize emails by priority, identify action items, and summarize content - You can also use this tool to send emails Keep your responses concise and friendly. , model: openai/gpt-5.4, tools: { ...mcpTools }, memory, })对比 第 5 步的初始版本改动集中在instructions字段在原来的You are a helpful personal assistant that can help with various tasks.基础上补充了任务域声明email、scheduling social media posts和工具能力清单Gmail 的三类用途。tools: { ...mcpTools }与memory保持不变。3. 逐条拆解这段指令教会了 Agent 什么原文档明确了更新指令的核心价值让 Agent 理解何时以及如何使用它所拥有的工具。逐句分析指令内容对 Agent 决策的作用You are a helpful personal assistant that can help with various tasks such as email and scheduling social media posts.划定 Agent 的能力边界与高频任务场景让模型在用户请求与工具之间建立初步映射You have access to the following tools:显式声明工具可用性降低模型明明有工具却不用的概率1. Gmail: Use these tools for reading and categorizing emails from Gmail告诉模型 Gmail 工具集的适用场景读取、分类对应读取类工具You can categorize emails by priority, identify action items, and summarize content细化任务类型让模型知道可以执行优先级归类、动作项识别、内容摘要You can also use this tool to send emails声明写操作能力对应发送类工具避免模型因不确定而拒绝执行Keep your responses concise and friendly.约束输出风格属于全局行为规范这正是原文档强调的结论通过显式提及 Gmail 工具你给了 Agent 关于这些工具做什么、何时使用的上下文使它在响应用户请求时能做出更优的工具选择产出更准确、更有帮助的回答。4. 源码印证Mastra 如何加载与使用instructions要理解为什么这段字符串能影响 Agent 行为需要看 Mastra 框架内部对instructions的处理。4.1 类型定义在 packages/core/src/agent/agent.types.ts 中AgentConfig将instructions定义为可选的字符串instructions?: string;而从 packages/core/src/agent/agent.ts 可以看到构造时的默认值与赋值逻辑this.#instructions config.instructions ?? ;即未提供instructions时默认空字符串不会报错但正如本文所示留空的代价是 Agent 对工具的使用缺乏引导。4.2 运行时如何被注入提示词Mastra 的 Agent 在执行生成时会把instructions作为系统提示词的核心部分组装进请求见 packages/core/src/agent/agent.ts 附近的getInstructions()机制。在 Agent 循环中这段指令会与 memory 历史、工具定义一起交给模型指令 → 系统提示词instructions是模型理解任务的最顶层约束工具定义 → 函数声明tools: { ...mcpTools }展开出的工具以 JSON Schema 形式暴露给模型指令与工具协作指令负责策略层什么时候用什么工具工具 Schema 负责协议层工具的入参结构。这一点在 第 4 步的mcp.listTools()中已有铺垫listTools()异步连接每个已配置的 MCP 服务器、拉取可用工具并转成 Mastra Agent 可用的格式这些工具进入tools之后instructions就成了模型判断要不要调用的关键上下文。5. 进阶机制MCP 服务器自动注入的指导信息值得注意的是Mastra 不只依赖开发者手写指令——框架还提供了一条自动把 MCP 服务器元数据并入指令的通道。在 packages/core/src/agent/mcp-guidance.ts 中buildMcpServerGuidance()会遍历 Agent 的工具列表筛选出mcpMetadata.forwardInstructions true且携带非空serverInstructions的工具按服务器名去重、排序后生成形如## Guidance from MCP server zapier的 Markdown 段落追加进系统提示词每条指导默认被截断在 512 字符以内DEFAULT_INSTRUCTIONS_MAX_LENGTH可通过instructionsMaxLength覆盖防止指令膨胀。从源码结构看这意味着当某个 MCP 服务器显式声明了forwardInstructions时即使开发者不手写对应段落模型也能收到来自服务器侧的使用指导。但正如本课程强调的手写的instructions能把工具与你的具体任务场景比如个人助理负责邮件与社媒排期深度绑定这是通用服务器指导无法替代的——两者是互补关系而非替代关系。6. 完整链路回顾从 Zapier 配置到可用工具为了让本步骤的上下文更完整这里把前面几步的关键配置串联成一张配置—初始化—注册—引导链路图便于读者理解instructions所处的位置① MCP 配置来自 09-updating-mcp-config-zapier.mdconst mcp new MCPClient({ servers: { zapier: { url: new URL(process.env.ZAPIER_MCP_URL || ), requestInit: { headers: { Authorization: Bearer ${process.env.ZAPIER_MCP_API_KEY}, }, }, }, }, })zapier配置中该服务器的唯一标识url从.env读取的 Zapier MCP 端点new URL(...)负责构造 URL 对象|| 在环境变量缺失时兜底为空串避免崩溃requestInit.headers随每个请求发送的 HTTP 头其中Authorization: Bearer {apiKey}用于向 Zapier 验证身份。② 工具初始化来自 04-initializing-mcp-tools.mdconst mcpTools await mcp.listTools()③ 工具注册来自 05-updating-your-agent.mdtools: { ...mcpTools }, // 展开注入所有 MCP 工具④ 指令引导本文——即在第 2 节完成的instructions更新。链路完成后当用户在 playground 中说Get my last emailAgent 会经历解析请求 → 依据 instructions 判断这属于 Gmail 读取场景 → 匹配 Gmail 工具 → 携带身份令牌调用 Zapier MCP → 返回结果并组织成友好回复。7. 验证如何在 playground 中确认指令生效完成 instructions 更新后按 11-testing-zapier-integration.md 的步骤实测确保开发服务器运行中npm run dev打开 playgroundhttp://localhost:4111/尝试下达依赖 Zapier 的任务例如Get my last emailSend an email to youremailgmail.com with the subject Test and body Hello, this is a test email如果链路配置正确且指令引导到位Agent 应当能识别出任务需要 Zapier 工具、自动发起对应 API 调用并完成任务。测试本身就是验证 instructions 是否写对的手段若 Agent 反复拒绝调用工具或答非所问优先回看第 2 节的指令是否明确声明了工具用途与适用场景。8. 指令编写要点总结综合本步骤与仓库实现给出可直接落地的编写清单先声明任务域在第一段写明 Agent 的核心职责如 email、社媒排期帮助模型把用户意图映射到工具逐工具列用途对每个重要工具分组如1. Gmail:列出读取/分类/摘要/发送等具体动作动作粒度要与真实工具能力对齐避免夸大能力导致模型误用区分读写权限明确哪些操作是读取、哪些会对外产生副作用如发邮件让模型在调用写操作前有充分判断补充全局行为规范如Keep your responses concise and friendly.约束回复风格保持指令精简手写指令与 mcp-guidance.ts 的自动注入互补避免把工具 Schema 的细节重复写进指令那部分由工具定义承载随能力扩展迭代后续课程中继续接入 GitHub、Hacker News、文件系统等 MCP 服务器时GitHub 的同类步骤 展示了在指令中追加2. GitHub:分组的模式——指令是渐进生长的而不是一次写死的。结语更新 Agent 的 instructions 是 MCP 集成链条中成本最低、收益最直接的一环不需要改一行工具代码却决定了模型能否在正确时机调用 Zapier 的 Gmail 能力。Mastra 在 packages/core/src/agent/agent.ts 中把instructions作为系统提示词的核心装配进每一次生成同时通过 mcp-guidance.ts 提供服务器侧指令的自动注入——理解了这两条通道你就能像本课程一样用一段结构化的指令让 Agent 的每一次工具调用都有据可依。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考