提示詞區塊

提示詞區塊是由 Editor 管理、可重複使用的指示範本。Agent 的指示可結合內嵌文字、內嵌提示詞區塊，以及對獨立版本化提示詞區塊的參照。

Studio 工作流程與常見用途請參閱提示詞區塊。

區塊類型

類型	說明
text	只儲存在 Agent 版本中的任意格式文字
prompt_block	內嵌於 Agent 版本的提示詞區塊
prompt_block_ref	對獨立儲存且有版本管理之提示詞區塊的參照

被參照的區塊會在執行階段解析。缺少或未發布的參照會從最終指示中省略。解析後的非空區塊會以兩個換行字元串接。

下列範例會將已儲存的區塊與內嵌文字附加至 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}}

變數名稱必須以字母或底線開頭。後援值必須是以單引號或雙引號括住的字串。沒有後援值的未解析預留位置會保持不變。物件與陣列會序列化為 JSON。其他值則會轉換為字串。

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

顯示條件

提示詞區塊可包含顯示條件，用以控制是否將其納入最終指示。每個條件包含三個部分：

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

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

運算子	範例	納入區塊的條件
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 值

群組使用 AND 或 OR 結合條件。例如，下列群組會為使用付費方案的管理員納入區塊：

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

支援點號路徑。空群組會求值為 true，未知的運算子則會求值為 false。儲存類型最多支援三層巢狀群組。

沒有條件的區塊一律會納入。

程式化 API

透過 mastra.getEditor().prompt 存取提示詞區塊。完整方法簽章請參閱 prompt 命名空間。

建立提示詞區塊：

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"}}.',
})

更新現有區塊：

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() 分頁瀏覽已儲存的區塊、使用 getById() 擷取單一區塊，並使用 preview(blocks, context) 解析範本和帶有草稿參照的條件。

REST API

Mastra 伺服器的預設前綴為 /api。自訂伺服器前綴會變更下列路徑。

方法	路徑	說明
GET	/api/stored/prompt-blocks	列出已儲存的提示詞區塊
POST	/api/stored/prompt-blocks	建立已儲存的提示詞區塊
GET	/api/stored/prompt-blocks/:storedPromptBlockId	取得已儲存的提示詞區塊
PATCH	/api/stored/prompt-blocks/:storedPromptBlockId	更新已儲存的提示詞區塊
DELETE	/api/stored/prompt-blocks/:storedPromptBlockId	刪除已儲存的提示詞區塊

版本解析

執行階段參照會解析作用中且已發布的區塊。Editor 預覽會解析最新草稿。共用的草稿、發布與還原生命週期請參閱 Editor 版本管理。