> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Instructions

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

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

Instructions 始终位于上下文中，因此应只包含适用于每个请求的稳定行为。将条件性、篇幅较长或面向操作的内容移至 [`tools/`](https://mastra.zisheng.pro/reference/file-based-agents/tools) 或 [`skills/`](https://mastra.zisheng.pro/reference/file-based-agents/skills)，模型仅在相关时使用它们。

## 快速开始

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

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

## Instructions 应包含的内容

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

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

将条件性、篇幅较长或面向操作的指导移至 [`tools/`](https://mastra.zisheng.pro/reference/file-based-agents/tools) 或 [`skills/`](https://mastra.zisheng.pro/reference/file-based-agents/skills)，模型仅在相关时使用它们。

## TypeScript 中的 instructions

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

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

```typescript
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：

```typescript
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](https://mastra.zisheng.pro/reference/file-based-agents/subagents) 目录中，并遵循相同规则。

## 构建时行为

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

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

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

## 与 config 的优先级

Instructions 可以来自 `instructions.ts`、`instructions.md` 或 [`config.ts`](https://mastra.zisheng.pro/reference/file-based-agents/config) 中的 `instructions` 字段：

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

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