企业官网建设流程全解析

在 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 集成的完整步骤依次为：

1. 认识 MCP 是什么
2. 安装并配置 MCP 客户端
3. 在src/mastra/agents/index.ts中写入 Zapier 服务器配置
4. 初始化mcpTools = await mcp.listTools()
5. 把mcpTools展开进 Agent 的tools属性
6. 更新 Agent 的 instructions（本文）
7. 在 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 理解"何时"以及"如何使用"它所拥有的工具。逐句分析：

这正是原文档强调的结论：通过显式提及 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.md）

const 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.md）

const mcpTools = await mcp.listTools()

③ 工具注册（来自 05-updating-your-agent.md）

tools: { ...mcpTools }, // 展开注入所有 MCP 工具

④ 指令引导（本文）——即在第 2 节完成的instructions更新。

链路完成后，当用户在 playground 中说"Get my last email"，Agent 会经历：解析请求 → 依据 instructions 判断这属于 Gmail 读取场景 → 匹配 Gmail 工具 → 携带身份令牌调用 Zapier MCP → 返回结果并组织成友好回复。

7. 验证：如何在 playground 中确认指令生效

完成 instructions 更新后，按 11-testing-zapier-integration.md 的步骤实测：

1. 确保开发服务器运行中：npm run dev
2. 打开 playground：http://localhost:4111/
3. 尝试下达依赖 Zapier 的任务，例如：
   • "Get my last email"
   • "Send an email to youremail@gmail.com with the subject 'Test' and body 'Hello, this is a test email'"

如果链路配置正确且指令引导到位，Agent 应当能识别出任务需要 Zapier 工具、自动发起对应 API 调用并完成任务。测试本身就是验证 instructions 是否写对的手段：若 Agent 反复拒绝调用工具或答非所问，优先回看第 2 节的指令是否明确声明了工具用途与适用场景。

8. 指令编写要点总结

综合本步骤与仓库实现，给出可直接落地的编写清单：

1. 先声明任务域：在第一段写明 Agent 的核心职责（如 email、社媒排期），帮助模型把用户意图映射到工具；
2. 逐工具列用途：对每个重要工具分组（如1. Gmail:），列出"读取/分类/摘要/发送"等具体动作，动作粒度要与真实工具能力对齐，避免夸大能力导致模型误用；
3. 区分读写权限：明确哪些操作是读取、哪些会对外产生副作用（如发邮件），让模型在调用写操作前有充分判断；
4. 补充全局行为规范：如"Keep your responses concise and friendly."，约束回复风格；
5. 保持指令精简：手写指令与 mcp-guidance.ts 的自动注入互补，避免把工具 Schema 的细节重复写进指令（那部分由工具定义承载）；
6. 随能力扩展迭代：后续课程中继续接入 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