Prompt blocks

Prompt block 是由 Editor 管理的可复用指令模板。Agent 的指令可以组合内联文本、嵌入式 prompt block，以及对独立版本化 prompt block 的引用。

有关 Studio 工作流和常见用法，请参阅 Prompt block。

Block 类型

类型	描述
text	仅存储在 Agent 版本中的自由格式文本
prompt_block	嵌入在 Agent 版本中的 prompt block
prompt_block_ref	对独立存储和版本化的 prompt block 的引用

引用的 block 会在运行时解析。缺失或未发布的引用会从最终指令中省略。解析后的非空 block 使用两个换行符连接。

以下示例将已存储的 block 和内联文本附加到 Agent：

src/scripts/attach-prompt.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.update({
  id: 'support-agent',
  instructions: [
    { type: 'prompt_block_ref', id: 'brand-voice' },
    { type: 'text', content: 'Answer only questions about Acme products.' },
  ],
})

模板值

模板会在运行时从 request context 解析值。

语法	Request context	输出
{{userName}}	{ userName: 'Maya' }	Maya
{{user.name}}	{ user: { name: 'Maya' } }	Maya
{{task || 'request'}}	{}	request
{{missingValue}}	{}	{{missingValue}}

变量名必须以字母或下划线开头。Fallback 必须是单引号或双引号字符串。没有 fallback 的未解析占位符会保持不变。对象和数组会序列化为 JSON，其他值会转换为字符串。

通过 request context 传递值。Editor 不会读取单独的 Agent variables 字段。

显示条件

Prompt block 可以包含显示条件，用于控制是否将其纳入最终指令。每个条件包含三部分：

• Key：要检查的 request context 字段，例如 user.role 或 account.plan。
• Operator：要执行的比较，例如 equals、contains 或 exists。
• Value：用于比较的值。exists 和 not_exists operator 不需要此值。

例如，仅当 request context 包含 { user: { role: 'admin' } } 时，条件 user.role equals admin 才会包含该 block。

Operator	示例	包含该 block 的条件
equals / not_equals	user.role 等于 admin	字段严格等于或不等于该值
contains / not_contains	user.tags 包含 beta	字符串包含该值，或数组包含该项
greater_than / less_than	order.total 大于 100	数值字段大于或小于该值
greater_than_or_equal / less_than_or_equal	account.seats 大于或等于 10	数值字段大于等于或小于等于该值
in / not_in	user.region 位于 ['US', 'CA'] 中	字段在或不在给定数组中
exists / not_exists	account.plan 存在	字段具有或不具有非 null 值

Group 使用 AND 或 OR 组合条件。例如，以下 group 会为使用付费方案的管理员包含一个 block：

const rules = {
  operator: 'AND',
  conditions: [
    {
      field: 'user.role',
      operator: 'equals',
      value: 'admin',
    },
    {
      field: 'account.plan',
      operator: 'in',
      value: ['pro', 'enterprise'],
    },
  ],
}

支持点路径。空 group 的求值结果为 true，未知 operator 的求值结果为 false。存储类型最多支持三层嵌套 group。

不带条件的 block 始终会被包含。

编程 API

通过 mastra.getEditor().prompt 访问 prompt block。完整的方法签名请参阅 prompt 命名空间。

创建 prompt block：

src/scripts/seed-prompts.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.prompt.create({
  id: 'brand-voice',
  name: 'Brand voice',
  description: 'Acme tone and style guidelines',
  content: 'Write in a friendly, concise tone. Address the user as {{userName || "there"}}.',
})

更新现有 block：

src/scripts/update-prompt.ts

await editor.prompt.update({
  id: 'brand-voice',
  content: 'Write in a friendly, concise tone. Greet the user by name when available.',
})

内容发生变化时，update() 会创建新草稿。使用 list() 对已存储 block 进行分页，使用 getById() 获取单个 block，使用 preview(blocks, context) 通过草稿引用解析模板和条件。

REST API

Mastra 的默认服务器前缀为 /api。自定义服务器前缀会更改下列路径。

方法	路径	描述
GET	/api/stored/prompt-blocks	列出已存储的 prompt block
POST	/api/stored/prompt-blocks	创建已存储的 prompt block
GET	/api/stored/prompt-blocks/:storedPromptBlockId	获取已存储的 prompt block
PATCH	/api/stored/prompt-blocks/:storedPromptBlockId	更新已存储的 prompt block
DELETE	/api/stored/prompt-blocks/:storedPromptBlockId	删除已存储的 prompt block

版本解析

运行时引用会解析当前已发布 block。Editor 预览会解析最新草稿。有关共享的草稿、发布和恢复生命周期，请参阅 Editor 版本控制。