跳至主要內容

PrefillErrorHandler

PrefillErrorHandler 是一個 error processor，用於處理助理回應預填錯誤。如果對話以助理訊息結束，而模型因將其解讀為預填助理回應而拒絕請求，就會出現此錯誤。

偵測到錯誤時，Processor 會傳送一個隱藏的 system-reminder signal，以 continue 作為其內容，並發出重試指示。該提醒會以 signal metadata 的形式持久保存，因此可用於重試重建及原始記錄，而面向標準 UI 的訊息轉換則會將其隱藏。

如要 Mastra 從助理預填拒絕中復原（例如 Anthropic 的「assistant message prefill」以及 Qwen/llama.cpp 的「assistant response prefill is incompatible with enable_thinking」錯誤），請將此 Processor 加入 errorProcessors。

運作方式
運作方式 的直接連結

  1. LLM API 呼叫因已知的助理預填拒絕訊息而失敗
  2. PrefillErrorHandler 檢查這是否為首次重試
  3. 它傳送一個隱藏的 system-reminder signal，以 continue 作為其內容
  4. 它傳回 { retry: true }，指示應使用修改後的訊息重試 LLM 呼叫

Processor 現在會直接因應 API 拒絕，而不再重新檢查對話目前是否以助理訊息結束。即使末端訊息的形式已在上游完成轉換，Provider 仍可能因預填語義而拒絕請求；此做法可令 Processor 妥善處理這些情況。

使用範例
使用範例 的直接連結

對於任何應在助理預填失敗後重試的 Agent，請將 PrefillErrorHandler 加入 errorProcessors：

src/mastra/agents/my-agent.ts
import { Agent } from '@mastra/core/agent'
import { PrefillErrorHandler } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'my-agent',
  name: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'anthropic/claude-opus-4-7',
  errorProcessors: [new PrefillErrorHandler()],
})

如需自訂復原行為，請提供具備 processAPIError 方法的自訂 error processor：

src/mastra/agents/custom-error-handling.ts
import { Agent } from '@mastra/core/agent'
import type { Processor } from '@mastra/core/processors'

const customErrorHandler: Processor = {
  id: 'custom-prefill-error-handler',
  processAPIError({ error, messageList, retryCount }) {
    // Your custom logic here
  },
}

export const agent = new Agent({
  id: 'my-agent',
  name: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'anthropic/claude-opus-4-7',
  errorProcessors: [customErrorHandler],
})

建構函數參數
建構函數參數 的直接連結

PrefillErrorHandler 不接受任何建構函數參數。

屬性
屬性 的直接連結

id:

'prefill-error-handler'
Processor 識別符。

name:

'Prefill Error Handler'
Processor 顯示名稱。

processAPIError:

(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void
透過傳送隱藏的 system reminder signal 並發出重試指示，處理已知的助理預填錯誤。只會在首次重試時觸發。
On this page