Agent.generateLegacy() (레거시)

경고

더 이상 사용되지 않음: 이 방법은 더 이상 사용되지 않으며 레거시 Model 어댑터에서만 작동합니다. 현재 Model 어댑터의 경우 다음을 사용하십시오..generate() instead.

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

사용예
사용예에 대한 직접 링크

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

생성 프로세스를 위한 선택적 구성입니다.

AgentGenerateOptions

abortSignal?:

AbortSignal

Agent 실행을 중단할 수 있는 신호 객체입니다. 신호가 중단되면 진행 중인 모든 작업이 종료됩니다.

context?:

CoreMessage[]

Agent에 제공할 추가 컨텍스트 메시지입니다.

structuredOutput?:

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

더 나은 개발자 경험을 제공하는 구조화된 출력 생성을 활성화합니다. 내부적으로 StructuredOutputProcessor를 자동 생성하여 사용합니다.

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

schema:

z.ZodSchema<S>

출력을 검증하는 데 사용할 Zod 스키마입니다.

model:

MastraLanguageModel

내부 구조화 Agent에 사용할 Model입니다.

errorStrategy?:

'strict' | 'warn' | 'fallback'

구문 분석 또는 검증 실패 시 사용할 전략입니다. 기본값은 'strict'입니다.

fallbackValue?:

errorStrategy가 'fallback'일 때 사용할 대체 값입니다.

instructions?:

string

구조화 Agent를 위한 사용자 지정 지침입니다.

outputProcessors?:

Processor[]

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

inputProcessors?:

Processor[]

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

experimental_output?:

Zod schema | JsonSchema7

권장되는 방식은 structuredOutput 속성을 사용하는 것입니다. 텍스트 생성 및 Tool 호출과 함께 구조화된 출력 생성을 활성화합니다. Model은 제공된 스키마를 준수하는 응답을 생성합니다.

instructions?:

string

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

output?:

Zod schema | JsonSchema7

예상되는 출력 구조를 정의합니다. JSON Schema 객체 또는 Zod 스키마를 사용할 수 있습니다.

memory?:

object

Memory 구성입니다. Memory를 관리하는 데 권장되는 방식입니다.

object

thread:

string | { id: string; metadata?: Record<string, any>, title?: string }

대화 스레드입니다. 문자열 ID 또는 id와 선택적 metadata가 포함된 객체로 지정합니다.

resource:

string

스레드와 연결된 사용자 또는 리소스의 식별자입니다.

options?:

MemoryConfig

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

maxSteps?:

number

허용되는 최대 실행 단계 수입니다.

maxRetries?:

number

최대 재시도 횟수입니다. 재시도를 비활성화하려면 0으로 설정하세요.

onStepFinish?:

GenerateTextOnStepFinishCallback<any> | never

각 실행 단계 후에 호출되는 콜백 함수입니다. 단계 세부 정보를 JSON 문자열로 받습니다. 구조화된 출력에는 사용할 수 없습니다.

runId?:

string

이 생성 실행의 고유 ID입니다. 추적 및 디버깅에 유용합니다.

telemetry?:

TelemetrySettings

생성 중 텔레메트리 수집 설정입니다.

TelemetrySettings

isEnabled?:

boolean

텔레메트리를 활성화하거나 비활성화합니다. 실험 단계에서는 기본적으로 비활성화됩니다.

recordInputs?:

boolean

입력 기록을 활성화하거나 비활성화합니다. 기본적으로 활성화됩니다. 민감한 정보가 기록되지 않도록 입력 기록을 비활성화할 수 있습니다.

recordOutputs?:

boolean

출력 기록을 활성화하거나 비활성화합니다. 기본적으로 활성화됩니다. 민감한 정보가 기록되지 않도록 출력 기록을 비활성화할 수 있습니다.

functionId?:

string

이 함수의 식별자입니다. 텔레메트리 데이터를 함수별로 그룹화하는 데 사용됩니다.

temperature?:

number

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

toolChoice?:

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

생성 중 Agent가 Tool을 사용하는 방식을 제어합니다.

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

'auto':

string

Tool 사용 여부를 Model이 결정하도록 합니다(기본값).

'none':

string

Tool을 사용하지 않습니다.

'required':

string

Model이 하나 이상의 Tool을 사용하도록 요구합니다.

{ type: 'tool'; toolName: string }:

object

Model이 이름으로 지정된 특정 Tool을 사용하도록 요구합니다.

toolsets?:

ToolsetsInput

생성 중 Agent에서 사용할 수 있도록 제공할 추가 Tool 세트입니다.

clientTools?:

ToolsInput

요청의 'client' 측에서 실행되는 Tool입니다. 이러한 Tool은 정의에 execute 함수가 없습니다.

hooks?:

ToolHooks

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

savePerStep?:

boolean

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

providerOptions?:

Record<string, Record<string, JSONValue>>

기본 LLM Provider로 전달되는 추가 Provider별 옵션입니다. 구조는 { providerName: { optionKey: value } }입니다. Mastra는 AI SDK를 확장하므로 전체 Provider 옵션은 AI SDK 문서를 참조하세요.

Record<string, Record<string, JSONValue>>

openai?:

Record<string, JSONValue>

OpenAI 전용 옵션입니다. 예: { reasoningEffort: 'high' }

anthropic?:

Record<string, JSONValue>

Anthropic 전용 옵션입니다. 예: { maxTokens: 1000 }

google?:

Record<string, JSONValue>

Google 전용 옵션입니다. 예: { safetySettings: [...] }

[providerName]?:

Record<string, JSONValue>

기타 Provider별 옵션입니다. 키는 Provider 이름이고 값은 Provider별 옵션의 레코드입니다.

requestContext?:

RequestContext

종속성 주입 및 컨텍스트 정보를 위한 Request Context입니다.

maxTokens?:

number

생성할 최대 토큰 수입니다.

topP?:

number

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

topK?:

number

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

presencePenalty?:

number

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

frequencyPenalty?:

number

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

stopSequences?:

string[]

중지 시퀀스입니다. 설정하면 중지 시퀀스 중 하나가 생성될 때 Model이 텍스트 생성을 중지합니다.

seed?:

number

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

headers?:

Record<string, string | undefined>

요청과 함께 전송할 추가 HTTP 헤더입니다. HTTP 기반 Provider에만 적용됩니다.

보고
보고에 대한 직접 링크

text?:

string

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

object?:

object

output, structuredOutput 또는 experimental_output을 통해 스키마가 제공될 때 존재하는 생성된 구조화 응답입니다.

toolCalls?:

Array<ToolCall>

생성 프로세스 중 수행된 Tool 호출입니다. 텍스트 모드와 객체 모드 모두에 존재합니다.

Array<ToolCall>

toolName:

string

호출된 Tool의 이름입니다.

args:

any

Tool에 전달된 인수입니다.

새로운 API로 마이그레이션
새로운 API로 마이그레이션에 대한 직접 링크

정보

새로운 .generate() 메서드는 AI SDK v5+ 호환성, 향상된 구조화 출력 처리, 개선된 스트리밍 지원 등의 기능을 제공합니다. 자세한 마이그레이션 지침은 마이그레이션 가이드를 참조하세요.

빠른 마이그레이션 예
빠른 마이그레이션 예에 대한 직접 링크

이전(레거시)
이전(레거시)에 대한 직접 링크

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

이후(새 API)
이후(새 API)에 대한 직접 링크

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

확장된 사용 예
확장된 사용 예에 대한 직접 링크

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 }),
    ],
  },
)

사용예사용예에 대한 직접 링크

프로세서 재시도 지원프로세서 재시도 지원에 대한 직접 링크

매개변수매개변수에 대한 직접 링크

messages:

options?:

abortSignal?:

context?:

structuredOutput?:

schema:

model:

errorStrategy?:

fallbackValue?:

instructions?:

outputProcessors?:

inputProcessors?:

experimental_output?:

instructions?:

output?:

memory?:

thread:

resource:

options?:

maxSteps?:

maxRetries?:

onStepFinish?:

runId?:

telemetry?:

isEnabled?:

recordInputs?:

recordOutputs?:

functionId?:

temperature?:

toolChoice?:

'auto':

'none':

'required':

{ type: 'tool'; toolName: string }:

toolsets?:

clientTools?:

hooks?:

savePerStep?:

providerOptions?:

openai?:

anthropic?:

google?:

[providerName]?:

requestContext?:

maxTokens?:

topP?:

topK?:

presencePenalty?:

frequencyPenalty?:

stopSequences?:

seed?:

headers?:

보고보고에 대한 직접 링크

text?:

object?:

toolCalls?:

toolName:

args:

새로운 API로 마이그레이션새로운 API로 마이그레이션에 대한 직접 링크

빠른 마이그레이션 예빠른 마이그레이션 예에 대한 직접 링크

이전(레거시)이전(레거시)에 대한 직접 링크

이후(새 API)이후(새 API)에 대한 직접 링크

확장된 사용 예확장된 사용 예에 대한 직접 링크

관련된관련된에 대한 직접 링크

사용예
사용예에 대한 직접 링크

프로세서 재시도 지원
프로세서 재시도 지원에 대한 직접 링크

매개변수
매개변수에 대한 직접 링크

보고
보고에 대한 직접 링크

새로운 API로 마이그레이션
새로운 API로 마이그레이션에 대한 직접 링크

빠른 마이그레이션 예
빠른 마이그레이션 예에 대한 직접 링크

이전(레거시)
이전(레거시)에 대한 직접 링크

이후(새 API)
이후(새 API)에 대한 직접 링크

확장된 사용 예
확장된 사용 예에 대한 직접 링크

관련된
관련된에 대한 직접 링크