跳到主要内容

PrefillErrorHandler

PrefillErrorHandler 是一个错误 Processor，用于处理 assistant 响应预填充错误。当对话以 assistant 消息结尾，并且模型因将其解读为预填充 assistant 响应而拒绝请求时，就会出现此错误。

检测到错误后，Processor 会发送一个隐藏的 system-reminder signal，其内容为 continue，并发出重试 signal。该提醒会作为 signal metadata 持久化，因此在重试重建和原始历史记录中仍然可用，而面向标准 UI 的消息转换会将其隐藏。

如果希望 Mastra 从 assistant 预填充拒绝中恢复，请将此 Processor 添加到 errorProcessors（例如 Anthropic 的 "assistant message prefill"，以及 Qwen/llama.cpp 的 "assistant response prefill is incompatible with enable_thinking" 错误）。

工作原理
工作原理的直接链接

  1. LLM API 调用失败，并返回已知的 assistant 预填充拒绝消息
  2. PrefillErrorHandler 检查这是否为首次重试
  3. 它发送一个隐藏的 system-reminder signal，其内容为 continue
  4. 它返回 { retry: true }，表示应使用修改后的消息重试 LLM 调用

Processor 现在直接响应 API 拒绝，而不再重新检查对话当前是否以 assistant 消息结尾。因此，即使末尾消息的结构已在上游完成转换，当 Provider 仍因预填充语义拒绝请求时，它也能可靠处理。

用法示例
用法示例的直接链接

对于任何需要在 assistant 预填充失败时进行重试的 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()],
})

如需自定义恢复行为，请提供自己的错误 Processor，并实现 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'
Processor 标识符。

name:

'Prefill Error Handler'
Processor 显示名称。

processAPIError:

(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void
通过发送隐藏的 system reminder signal 并发出重试 signal 来处理已知的 assistant 预填充错误。仅在首次重试时触发。
On this page