Instructions

Agent 的 instructions 包含其始终启用的 system prompt：模型每一轮都会读取它。使用 instructions 定义 Agent 的身份、语气、角色和常驻规则。

请将其写在 Agent 根目录下的两个文件之一中。prompt 为固定文本时使用 instructions.md；prompt 需要代码时使用 instructions.ts，例如通过共享常量构建或按请求解析时。

Instructions 始终位于上下文中，因此应只包含适用于每个请求的稳定行为。将条件性、篇幅较长或面向操作的内容移至 tools/ 或 skills/，模型仅在相关时使用它们。

快速开始

在 Agent 根目录下添加 instructions.md。你写入的所有内容都会成为 prompt，因此最简版本只需一句话。

src/mastra/agents/weather/instructions.md

You are a helpful weather assistant. Answer questions about current conditions and forecasts.

Instructions 应包含的内容

有效的 instructions 应涵盖 Agent 行为中不会随请求变化的部分：

• 角色和身份
• 语气和风格
• 常驻规则
• 输出格式

将条件性、篇幅较长或面向操作的指导移至 tools/ 或 skills/，模型仅在相关时使用它们。

TypeScript 中的 instructions

当 Markdown 无法表达 prompt 时，请使用 instructions.ts。该文件默认导出字符串、system message 或返回其中一种类型的函数；agentInstructions() 会为导出提供类型，而不会改变其内容。

如果 prompt 是在代码中组装的（例如来自与应用其他部分共享的常量），请导出字符串：

src/mastra/agents/weather/instructions.ts

import { agentInstructions } from '@mastra/core/agent'
import { SUPPORTED_UNITS } from '../../constants'

export default agentInstructions(`
You are a helpful weather assistant.
Report conditions using one of these units: ${SUPPORTED_UNITS.join(', ')}.
`)

如果 prompt 依赖请求，请导出函数。Mastra 会在每一轮调用该函数并传入 request context：

src/mastra/agents/support/instructions.ts

import { agentInstructions } from '@mastra/core/agent'

export default agentInstructions(({ requestContext }) => {
  const tier = requestContext.get('tier') ?? 'standard'
  return `You are a support agent. Treat this as a ${tier}-tier customer.`
})

该函数可以是 async，除了 requestContext 外还会接收 mastra，因此可在返回 prompt 前从 storage 或其他已注册组件读取数据。

这两个文件也可以放在子 Agent 目录中，并遵循相同规则。

构建时行为

instructions.md 和 instructions.ts 以不同方式进入部署后的 Agent：

• instructions.md：Mastra 读取文件，并在构建时将其内容内联到生成的代码中。
• instructions.ts：生成的代码会导入该模块，因此它会像其他 TypeScript 文件一样被打包，并且可以从项目的其他位置导入内容。

在 mastra dev 下，编辑任一文件都会触发重新构建。在已部署的应用中，这两个文件都不会在运行时从磁盘读取，因此更改会在下次构建后生效。

与 config 的优先级

Instructions 可以来自 instructions.ts、instructions.md 或 config.ts 中的 instructions 字段：

• config.ts 中运行时定义（函数）的 instructions 优先于这两个文件。
• 其他情况下，instructions.ts 优先于 instructions.md。
• instructions.md 优先于 config.ts 中静态的 instructions 字符串。
• 如果三者都不存在，构建会失败并指出 Agent 目录名称。

在多个位置定义 instructions 时，Mastra 会记录一条警告，指出这两个来源以及最终采用哪一个。每个 Agent 请只使用一个来源。