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

# Agent.generateLegacy() (레거시)

> **경고:** **더 이상 사용되지 않음**: 이 방법은 더 이상 사용되지 않으며 레거시 Model 어댑터에서만 작동합니다. 현재 Model 어댑터의 경우 다음을 사용하십시오.[`.generate()`](https://mastra.zisheng.pro/ko/reference/agents/generate) instead.

`.generateLegacy()` 메서드는 Agent 생성 API의 레거시 버전으로, 레거시 Model 어댑터와 함께 사용하여 텍스트 또는 구조화된 응답을 생성합니다. 이 메서드는 메시지와 선택적 생성 옵션을 받습니다.

## 사용예

```typescript
await agent.generateLegacy('message for agent')
```

## 프로세서 재시도 지원

`generateLegacy()`는 오류 프로세서나 `maxProcessorRetries`를 실행하지 않습니다. 대신 레거시 AI SDK 생성 경로를 사용합니다. 레거시 Model 어댑터를 사용하는 스코어러 심사위원은 `generateLegacy()`를 호출합니다. 이러한 심사위원에는 Mastra의 현재 생성 API를 사용하는 스코어러 심사위원에게 제공되는 통합 `StreamErrorRetryProcessor` 예산이 적용되지 않습니다. 오류 프로세서 재시도가 필요하면 현재 Model 어댑터를 사용하세요. 레거시 `maxRetries` 옵션은 별도로 유지되며 기본값은 `2`입니다.

## 매개변수

**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): Agent에 전송할 메시지입니다. 단일 문자열, 문자열 배열 또는 멀티모달 콘텐츠(텍스트, 이미지 등)가 포함된 구조화된 메시지 객체를 사용할 수 있습니다.

**options** (`AgentGenerateOptions`): 생성 프로세스를 위한 선택적 구성입니다.

**options.abortSignal** (`AbortSignal`): Agent 실행을 중단할 수 있는 신호 객체입니다. 신호가 중단되면 진행 중인 모든 작업이 종료됩니다.

**options.context** (`CoreMessage[]`): Agent에 제공할 추가 컨텍스트 메시지입니다.

**options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): 더 나은 개발자 경험을 제공하는 구조화된 출력 생성을 활성화합니다. 내부적으로 StructuredOutputProcessor를 자동 생성하여 사용합니다.

**options.structuredOutput.schema** (`z.ZodSchema<S>`): 출력을 검증하는 데 사용할 Zod 스키마입니다.

**options.structuredOutput.model** (`MastraLanguageModel`): 내부 구조화 Agent에 사용할 Model입니다.

**options.structuredOutput.errorStrategy** (`'strict' | 'warn' | 'fallback'`): 구문 분석 또는 검증 실패 시 사용할 전략입니다. 기본값은 'strict'입니다.

**options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): errorStrategy가 'fallback'일 때 사용할 대체 값입니다.

**options.structuredOutput.instructions** (`string`): 구조화 Agent를 위한 사용자 지정 지침입니다.

**options.outputProcessors** (`Processor[]`): Agent에 설정된 출력 프로세서를 재정의합니다. 출력 프로세서는 Agent의 메시지가 사용자에게 반환되기 전에 메시지를 수정하거나 검증할 수 있습니다. processOutputResult와 processOutputStream 함수 중 하나 이상을 구현해야 합니다.

**options.inputProcessors** (`Processor[]`): Agent에 설정된 입력 프로세서를 재정의합니다. 입력 프로세서는 메시지가 Agent에서 처리되기 전에 메시지를 수정하거나 검증할 수 있습니다. processInput 함수를 구현해야 합니다.

**options.experimental\_output** (`Zod schema | JsonSchema7`): 권장되는 방식은 structuredOutput 속성을 사용하는 것입니다. 텍스트 생성 및 Tool 호출과 함께 구조화된 출력 생성을 활성화합니다. Model은 제공된 스키마를 준수하는 응답을 생성합니다.

**options.instructions** (`string`): 이 특정 생성에서 Agent의 기본 지침을 재정의하는 사용자 지정 지침입니다. 새 Agent 인스턴스를 만들지 않고 Agent 동작을 동적으로 변경할 때 유용합니다.

**options.output** (`Zod schema | JsonSchema7`): 예상되는 출력 구조를 정의합니다. JSON Schema 객체 또는 Zod 스키마를 사용할 수 있습니다.

**options.memory** (`object`): Memory 구성입니다. Memory를 관리하는 데 권장되는 방식입니다.

**options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): 대화 스레드입니다. 문자열 ID 또는 id와 선택적 metadata가 포함된 객체로 지정합니다.

**options.memory.resource** (`string`): 스레드와 연결된 사용자 또는 리소스의 식별자입니다.

**options.memory.options** (`MemoryConfig`): 메시지 기록 및 의미론적 회상과 같은 Memory 동작을 구성합니다. 아래의 MemoryConfig를 참조하세요.

**options.maxSteps** (`number`): 허용되는 최대 실행 단계 수입니다.

**options.maxRetries** (`number`): 최대 재시도 횟수입니다. 재시도를 비활성화하려면 0으로 설정하세요.

**options.onStepFinish** (`GenerateTextOnStepFinishCallback<any> | never`): 각 실행 단계 후에 호출되는 콜백 함수입니다. 단계 세부 정보를 JSON 문자열로 받습니다. 구조화된 출력에는 사용할 수 없습니다.

**options.runId** (`string`): 이 생성 실행의 고유 ID입니다. 추적 및 디버깅에 유용합니다.

**options.telemetry** (`TelemetrySettings`): 생성 중 텔레메트리 수집 설정입니다.

**options.telemetry.isEnabled** (`boolean`): 텔레메트리를 활성화하거나 비활성화합니다. 실험 단계에서는 기본적으로 비활성화됩니다.

**options.telemetry.recordInputs** (`boolean`): 입력 기록을 활성화하거나 비활성화합니다. 기본적으로 활성화됩니다. 민감한 정보가 기록되지 않도록 입력 기록을 비활성화할 수 있습니다.

**options.telemetry.recordOutputs** (`boolean`): 출력 기록을 활성화하거나 비활성화합니다. 기본적으로 활성화됩니다. 민감한 정보가 기록되지 않도록 출력 기록을 비활성화할 수 있습니다.

**options.telemetry.functionId** (`string`): 이 함수의 식별자입니다. 텔레메트리 데이터를 함수별로 그룹화하는 데 사용됩니다.

**options.temperature** (`number`): Model 출력의 무작위성을 제어합니다. 값이 높을수록(예: 0.8) 출력이 더 무작위적으로 생성되고, 값이 낮을수록(예: 0.2) 더 집중적이고 결정론적으로 생성됩니다.

**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): 생성 중 Agent가 Tool을 사용하는 방식을 제어합니다.

**options.toolChoice.'auto'** (`string`): Tool 사용 여부를 Model이 결정하도록 합니다(기본값).

**options.toolChoice.'none'** (`string`): Tool을 사용하지 않습니다.

**options.toolChoice.'required'** (`string`): Model이 하나 이상의 Tool을 사용하도록 요구합니다.

**options.toolChoice.{ type: 'tool'; toolName: string }** (`object`): Model이 이름으로 지정된 특정 Tool을 사용하도록 요구합니다.

**options.toolsets** (`ToolsetsInput`): 생성 중 Agent에서 사용할 수 있도록 제공할 추가 Tool 세트입니다.

**options.clientTools** (`ToolsInput`): 요청의 'client' 측에서 실행되는 Tool입니다. 이러한 Tool은 정의에 execute 함수가 없습니다.

**options.hooks** (`ToolHooks`): Tool 호출 전후에 실행되는 실행별 훅입니다. 이 실행에 대해 일치하는 Agent 수준 훅을 재정의합니다. beforeToolCall에서 { proceed: false, output }을 반환하여 Tool 호출을 건너뛸 수 있습니다.

**options.savePerStep** (`boolean`): 각 생성 단계가 완료된 후 메시지를 점진적으로 저장합니다(기본값: false). 관찰 Memory가 활성화되면 내부적으로 비활성화됩니다.

**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): 기본 LLM Provider로 전달되는 추가 Provider별 옵션입니다. 구조는 { providerName: { optionKey: value } }입니다. Mastra는 AI SDK를 확장하므로 전체 Provider 옵션은 AI SDK 문서를 참조하세요.

**options.providerOptions.openai** (`Record<string, JSONValue>`): OpenAI 전용 옵션입니다. 예: { reasoningEffort: 'high' }

**options.providerOptions.anthropic** (`Record<string, JSONValue>`): Anthropic 전용 옵션입니다. 예: { maxTokens: 1000 }

**options.providerOptions.google** (`Record<string, JSONValue>`): Google 전용 옵션입니다. 예: { safetySettings: \[...] }

**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): 기타 Provider별 옵션입니다. 키는 Provider 이름이고 값은 Provider별 옵션의 레코드입니다.

**options.requestContext** (`RequestContext`): 종속성 주입 및 컨텍스트 정보를 위한 Request Context입니다.

**options.maxTokens** (`number`): 생성할 최대 토큰 수입니다.

**options.topP** (`number`): 핵 샘플링입니다. 0과 1 사이의 숫자입니다. temperature와 topP 중 하나만 설정하는 것이 좋습니다.

**options.topK** (`number`): 각 후속 토큰에 대해 상위 K개 옵션에서만 샘플링합니다. 확률이 낮은 'long tail' 응답을 제거하는 데 사용됩니다.

**options.presencePenalty** (`number`): 존재 페널티 설정입니다. Model이 Prompt에 이미 있는 정보를 반복할 가능성에 영향을 줍니다. -1(반복 증가)에서 1(최대 페널티, 반복 감소) 사이의 숫자입니다.

**options.frequencyPenalty** (`number`): 빈도 페널티 설정입니다. Model이 같은 단어나 구문을 반복해서 사용할 가능성에 영향을 줍니다. -1(반복 증가)에서 1(최대 페널티, 반복 감소) 사이의 숫자입니다.

**options.stopSequences** (`string[]`): 중지 시퀀스입니다. 설정하면 중지 시퀀스 중 하나가 생성될 때 Model이 텍스트 생성을 중지합니다.

**options.seed** (`number`): 무작위 샘플링에 사용할 시드(정수)입니다. 설정되어 있고 Model에서 지원하면 호출 시 결정론적 결과가 생성됩니다.

**options.headers** (`Record<string, string | undefined>`): 요청과 함께 전송할 추가 HTTP 헤더입니다. HTTP 기반 Provider에만 적용됩니다.

## 보고

**text** (`string`): 생성된 텍스트 응답입니다. 출력이 'text'일 때 존재합니다(스키마가 제공되지 않은 경우).

**object** (`object`): output, structuredOutput 또는 experimental\_output을 통해 스키마가 제공될 때 존재하는 생성된 구조화 응답입니다.

**toolCalls** (`Array<ToolCall>`): 생성 프로세스 중 수행된 Tool 호출입니다. 텍스트 모드와 객체 모드 모두에 존재합니다.

**toolCalls.toolName** (`string`): 호출된 Tool의 이름입니다.

**toolCalls.args** (`any`): Tool에 전달된 인수입니다.

## 새로운 API로 마이그레이션

> **정보:** 새로운 `.generate()` 메서드는 AI SDK v5+ 호환성, 향상된 구조화 출력 처리, 개선된 스트리밍 지원 등의 기능을 제공합니다. 자세한 마이그레이션 지침은 [마이그레이션 가이드](https://mastra.zisheng.pro/ko/guides/migrations/vnext-to-standard-apis)를 참조하세요.

### 빠른 마이그레이션 예

#### 이전(레거시)

```typescript
const result = await agent.generateLegacy('message', {
  temperature: 0.7,
  maxSteps: 3,
})
```

#### 이후(새 API)

```typescript
const result = await agent.generate('message', {
  modelSettings: {
    temperature: 0.7,
  },
  maxSteps: 3,
})
```

## 확장된 사용 예

```typescript
import { z } from 'zod'
import { ModerationProcessor, TokenLimiterProcessor } from '@mastra/core/processors'

await agent.generateLegacy(
  [
    { role: 'user', content: 'message for agent' },
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'message for agent',
        },
        {
          type: 'image',
          imageUrl: 'https://example.com/image.jpg',
          mimeType: 'image/jpeg',
        },
      ],
    },
  ],
  {
    temperature: 0.7,
    maxSteps: 3,
    memory: {
      thread: 'user-123',
      resource: 'test-app',
    },
    toolChoice: 'auto',
    providerOptions: {
      openai: {
        reasoningEffort: 'high',
      },
    },
    // Structured output with better DX
    structuredOutput: {
      schema: z.object({
        sentiment: z.enum(['positive', 'negative', 'neutral']),
        confidence: z.number(),
      }),
      model: 'openai/gpt-5.6-sol',
      errorStrategy: 'warn',
    },
    // Output processors for response validation
    outputProcessors: [
      new ModerationProcessor({ model: 'openai/gpt-5-mini' }),
      new TokenLimiterProcessor({ maxTokens: 1000 }),
    ],
  },
)
```

## 관련된

- [마이그레이션 가이드](https://mastra.zisheng.pro/ko/guides/migrations/vnext-to-standard-apis)
- [새로운 .generate() 메소드](https://mastra.zisheng.pro/ko/reference/agents/generate)
- [응답 생성](https://mastra.zisheng.pro/ko/docs/agents/overview)
- [스트리밍 응답](https://mastra.zisheng.pro/ko/docs/agents/overview)