ProviderHistoryCompat

그만큼ProviderHistoryCompat프로세서는 공급자별 기록 비호환성을 처리합니다. 공급자 호출 전에 아웃바운드 언어 Model Prompt를 다시 작성하거나 API 오류에 반응하고 복구된 메시지 기록으로 다시 시도할 수 있습니다.

Agent가 Model 공급자 간에 전환하거나 공급자 간에 메시지 기록을 재사용할 수 있는 경우 이를 사용합니다. 또한 다른 공급자가 내보낸 필드를 거부하는 공급자도 처리합니다.

사용예

Agent에서 기본 제공 호환성 규칙을 모두 사용하려면 inputProcessors에 ProviderHistoryCompat를 추가하세요.

src/mastra/agents/my-agent.ts

import { Agent } from '@mastra/core/agent'
import { ProviderHistoryCompat } from '@mastra/core/processors'

export const agent = new Agent({
  id: 'my-agent',
  name: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'anthropic/claude-sonnet-4-5',
  inputProcessors: [new ProviderHistoryCompat()],
})

Mastra Agent는 이 프로세서를 자동으로 추가하지 않습니다. 공급자 기록 호환성 규칙, 반응형 API 오류 복구, 사용자 지정 규칙 또는 예측 가능한 프로세서 순서가 필요한 경우 명시적으로 추가하세요.

생성자 매개변수

opts?:

{ additionalRules?: CompatRule[] }

Provider 기록 호환성 규칙의 구성 옵션입니다.

Options

additionalRules?:

CompatRule[]

기본 제공 규칙 이후에 실행할 사용자 지정 호환성 규칙. 규칙은 발신 Prompt를 다시 작성하거나 API 오류가 일치한 후 저장된 메시지를 복구할 수 있습니다.

속성

id:

'provider-history-compat'

프로세서 식별자입니다.

name:

'Provider History Compat'

프로세서 표시 이름입니다.

processLLMRequest:

(args: ProcessLLMRequestArgs) => ProcessLLMRequestResult

Provider 호출 직전에 변환된 LanguageModelV2Prompt를 대상으로 선제적 호환성 규칙을 실행합니다. 반환된 Prompt 변경 사항은 일시적이며 Memory나 메시지 기록에 저장되지 않습니다.

processAPIError:

(args: ProcessAPIErrorArgs) => Promise<ProcessAPIErrorResult | void>

Provider가 요청을 거부할 때 반응형 호환성 규칙을 실행합니다. 일치하는 규칙은 메시지 목록을 변경하고 첫 번째 재시도에서 retry: true를 반환할 수 있습니다.

기본 제공 규칙

ProviderHistoryCompat다음과 같은 내장 호환성 규칙이 포함되어 있습니다.

규칙	Provider	실행 시점	동작
anthropic-tool-id-format	Anthropic	반응형 API 오류 복구	[a-zA-Z0-9_-] 이외의 문자가 포함된 Tool 호출 ID를 다시 작성하고 요청을 재시도합니다.
cerebras-strip-reasoning-content	Cerebras	선제적 Prompt 재작성	지원되지 않는 reasoning_content 필드로 직렬화되지 않도록 발신 Prompt에서 어시스턴트의 reasoning 부분을 제거합니다.
anthropic-strip-foreign-reasoning-content	Anthropic	선제적 Prompt 재작성	발신 Prompt에서 Anthropic이 아닌 어시스턴트의 reasoning 부분을 제거합니다. Anthropic 고유의 사고 기록은 유지됩니다.
선제적 규칙은 Mastra가 메시지를 Model Prompt 형식으로 변환한 후, Prompt를 Provider에 전송하기 전에 processLLMRequest에서 실행됩니다. 이러한 재작성은 현재 Provider 호출에만 영향을 줍니다.
반응형 규칙은 Provider가 요청을 거부한 후 processAPIError에서 실행됩니다. 저장된 messageList를 업데이트하고 재시도를 요청할 수 있습니다.

CompatRule

에이CompatRule defines one provider history compatibility fix:

import type { CompatRule } from '@mastra/core/processors'

const removeUnsupportedPromptParts: CompatRule = {
  name: 'remove-unsupported-prompt-parts',
  applyToPrompt({ prompt, model }) {
    // Return a modified LanguageModelV2Prompt, or undefined to leave it unchanged.
    return undefined
  },
}

name:

string

로그 및 디버깅에 사용하는 사람이 읽을 수 있는 규칙 식별자입니다.

errorPatterns?:

RegExp[]

Provider API 오류 메시지 및 응답 본문과 일치시킬 패턴입니다. fix를 구현하는 반응형 규칙에 필요합니다.

fix?:

(messages: MastraDBMessage[]) => boolean

일치하는 API 오류가 발생한 후 저장된 데이터베이스 메시지를 변경하는 반응형 수정입니다. 규칙이 메시지를 변경하여 요청을 재시도해야 할 때 true를 반환합니다.

applyToPrompt?:

(args: { prompt: LanguageModelV2Prompt; model: unknown }) => LanguageModelV2Prompt | undefined

현재 Provider 호출의 발신 Prompt를 다시 작성하는 선제적 수정입니다. Prompt를 변경할 필요가 없으면 undefined를 반환합니다.

맞춤 규칙

사용자 지정 규칙은 additionalRules로 전달하세요. 사용자 지정 규칙은 기본 제공 규칙 이후에 실행됩니다.

src/mastra/agents/custom-provider-compat.ts

import { Agent } from '@mastra/core/agent'
import { ProviderHistoryCompat, type CompatRule } from '@mastra/core/processors'

const stripUnsupportedAssistantMetadata: CompatRule = {
  name: 'strip-unsupported-assistant-metadata',
  applyToPrompt({ prompt, model }) {
    if (typeof model !== 'string' || !model.startsWith('example-provider/')) {
      return undefined
    }

    let changed = false
    const nextPrompt = prompt.map(message => {
      if (message.role !== 'assistant' || typeof message.content === 'string') {
        return message
      }

      const nextContent = message.content.map(part => {
        if (!('providerOptions' in part)) return part
        changed = true
        const { providerOptions: _providerOptions, ...rest } = part
        return rest
      })

      return { ...message, content: nextContent }
    })

    return changed ? nextPrompt : undefined
  },
}

export const agent = new Agent({
  id: 'custom-provider-agent',
  name: 'custom-provider-agent',
  instructions: 'You are a helpful assistant.',
  model: 'example-provider/model',
  inputProcessors: [
    new ProviderHistoryCompat({
      additionalRules: [stripUnsupportedAssistantMetadata],
    }),
  ],
})

Memory에 저장하지 않아야 하는 Provider별 재작성에는 applyToPrompt를 사용하세요. Provider가 저장된 메시지 기록을 거부하고 복구된 기록을 이후 턴에서 재사용해야 할 때는 errorPatterns와 함께 fix를 사용하세요.

관련된

• 프로세서 인터페이스
• 프로세서
• PrefillErrorHandler