Prompt block

Prompt block 是由 Editor 管理、可重用的指令 template。Agent 的指令可結合 inline 文字、嵌入式 prompt block，以及對獨立版本化 prompt block 的引用。

Studio 工作流程及常見用途請參閱 Prompt block。

Block 類型

類型	描述
text	只儲存在 Agent 版本中的自由格式文字
prompt_block	嵌入 Agent 版本的 prompt block
prompt_block_ref	對獨立儲存及版本化 prompt block 的引用

被引用的 block 會在執行階段解析。遺失或未發佈的引用會從最終指令中略過。解析後的非空 block 會以兩個換行符連接。

以下範例將已儲存的 block 及 inline 文字附加至 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.' },
  ],
})

Template 值

Template 會在執行階段從 request context 解析值。

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

變數名稱必須以字母或底線開首。Fallback 必須是以單引號或雙引號括起的字串。沒有 fallback 而無法解析的 placeholder 會維持不變。物件和陣列會序列化為 JSON，其他值則會轉換為字串。

請透過 request context 傳入值。Editor 不會讀取另一個 Agent variables 欄位。

顯示條件

Prompt block 可包含顯示條件，用於控制它是否包括在最終指令內。每個條件分為三部分：

• 鍵： 要檢查的 request context 欄位，例如 user.role 或 account.plan。
• 運算子： 要進行的比較，例如 equals、contains 或 exists。
• 值： 要比較的值。exists 和 not_exists 運算子不需要值。

例如，條件 user.role equals admin 只會在 request context 包含 { user: { role: 'admin' } } 時加入 block。

運算子	範例	加入 block 的情況
equals / not_equals	user.role equals admin	欄位嚴格等於或不等於該值
contains / not_contains	user.tags contains beta	字串包含該值，或陣列包含該項目
greater_than / less_than	order.total greater than 100	數值欄位高於或低於該值
greater_than_or_equal / less_than_or_equal	account.seats greater than or equal to 10	數值欄位達到或超越該值
in / not_in	user.region in ['US', 'CA']	欄位在或不在提供的陣列中
exists / not_exists	account.plan exists	欄位有或沒有非 null 值

群組以 AND 或 OR 組合條件。例如，以下群組會為使用付費方案的管理員加入 block：

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

支援以點號表示的路徑。空群組的評估結果為 true，未知運算子的結果為 false。儲存類型最多支援三層巢狀群組。

沒有條件的 block 一律會加入。

編程 API

透過 mastra.getEditor().prompt 存取 prompt block。完整方法簽名請參閱 prompt namespace。

建立 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() 會建立新 draft。使用 list() 分頁瀏覽已儲存的 block、getById() 擷取一個 block，以及 preview(blocks, context) 透過 draft 引用解析 template 和條件。

REST API

Mastra 伺服器的預設 prefix 是 /api。自訂伺服器 prefix 會更改以下路徑。

方法	路徑	描述
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 預覽則解析最新 draft。共用的 draft、發佈和還原生命週期請參閱 Editor 版本控制。