> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# ProviderHistoryCompat

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

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

## 사용예

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

```typescript
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 기록 호환성 규칙의 구성 옵션입니다.

**opts.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:

```typescript
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`로 전달하세요. 사용자 지정 규칙은 기본 제공 규칙 이후에 실행됩니다.

```typescript
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`를 사용하세요.

## 관련된

- [프로세서 인터페이스](https://mastra.zisheng.pro/ko/reference/processors/processor-interface)
- [프로세서](https://mastra.zisheng.pro/ko/docs/agents/processors)
- [PrefillErrorHandler](https://mastra.zisheng.pro/ko/reference/processors/prefill-error-handler)