PrefillErrorHandler

PrefillErrorHandler 是一種錯誤處理器，用於處理助理回應預填錯誤。當對話以助理訊息結尾，而模型將其解讀為預填助理回應並因此拒絕請求時，就會發生此錯誤。

偵測到錯誤時，處理器會傳送一個隱藏的 system-reminder 訊號，其內容為 continue，並指示系統重試。此提醒會保存為訊號中繼資料，因此在重新建構重試內容與原始記錄時仍可使用，但標準的 UI 訊息轉換會將其隱藏。

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

運作方式

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

處理器現在會直接回應 API 拒絕，不再重新檢查對話目前是否以助理訊息結尾。因此，即使上游已轉換結尾訊息的形式，只要 Provider 因預填語意而拒絕請求，處理器仍能妥善處理。

使用範例

若 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 方法的自訂錯誤處理器：

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'

處理器識別碼。

name:

'Prefill Error Handler'

處理器顯示名稱。

processAPIError:

(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void

透過傳送隱藏的系統提醒訊號並指示重試，處理已知的助理預填錯誤。只會在第一次重試時觸發。

相關資源

• Processor 介面
• 防護機制