VNext에서 표준 API로 마이그레이션

현재v0.20.0~을 위한@mastra/core, 다음 변경 사항이 적용됩니다.

레거시 API(AI SDK v4)

기존 메서드의 이름이 변경되었으며 AI SDK v4 및 v1 Model과의 이전 버전 호환성을 유지합니다.

• .stream() → .streamLegacy()
• .generate() → .generateLegacy()

표준 API(AI SDK v5)

이제 AI SDK v5 및 v2 Model과 완벽하게 호환되는 모든 기능을 갖춘 최신 API입니다.

• .streamVNext() → .stream()
• .generateVNext() → .generate()

마이그레이션 경로

이미 .streamVNext() 및 .generateVNext()를 사용하고 있다면 찾기/바꾸기를 사용하여 각 메서드를 .stream() 및 .generate()로 변경하세요. 이전 .stream() 및 .generate()를 사용하고 있다면 업그레이드 여부를 결정하세요. 업그레이드하지 않으려면 찾기/바꾸기를 사용하여 .streamLegacy() 및 .generateLegacy()로 변경하세요. 필요에 맞는 마이그레이션 경로를 선택하세요.

AI SDK v4 Model을 계속 사용하세요.

• 모든 .stream() 및 .generate() 호출의 이름을 각각 .streamLegacy() 및 .generateLegacy()로 변경하세요.

추가 변경이 필요하지 않습니다.

AI SDK v5 Model을 계속 사용하세요.

• 모든 .streamVNext() 및 .generateVNext() 호출의 이름을 각각 .stream() 및 .generate()로 변경하세요.

추가 변경이 필요하지 않습니다.

AI SDK v4에서 v5로 업그레이드

• 모든 Model 제공자 패키지를 메이저 버전으로 업그레이드하세요.

이렇게 하면 이제 모든 Model이 v5 Model이 됩니다. 아래 가이드에 따라 주요 차이점을 이해하고 이에 따라 코드를 업데이트하세요.

주요 차이점

업데이트된 .stream() 및 .generate() 메서드는 동작, 호환성, 반환 타입 및 사용 가능한 옵션이 레거시 메서드와 다릅니다. 이 섹션에서는 마이그레이션할 때 알아야 할 가장 중요한 변경 사항을 설명합니다.

Model 버전 지원

레거시 API

• .generateLegacy()
• .streamLegacy()

지원만 가능AI SDK v4 models (specificationVersion: 'v1')

표준 API

• .generate()
• .stream()

지원만 가능AI SDK v5 models (specificationVersion: 'v2')

이는 명확한 오류 메시지와 함께 런타임에 적용됩니다.

반환 유형

레거시 API

• .generateLegacy() 반환: GenerateTextResult 또는 GenerateObjectResult

• .streamLegacy() 반환: StreamTextResult 또는 StreamObjectResult 자세한 내용은 다음 API 참조를 참조하세요.

• Agent.generateLegacy()

• Agent.streamLegacy() 표준 API

• .generate()

  • format: 'mastra'(기본값): MastraModelOutput.getFullOutput() 반환
  • format: 'aisdk': AISDKV5OutputStream.getFullOutput() 반환
  • 내부적으로 .stream()을 호출하고 .getFullOutput()을 기다림

• .stream()

  • format: 'mastra'(기본값): 반환MastraModelOutput<OUTPUT>
  • format: 'aisdk': 반품AISDKV5OutputStream<OUTPUT>

자세한 내용은 다음 API 참조를 참조하세요.

• Agent.생성()
• Agent.스트림()

형식 제어

레거시 API

format 옵션 없음: 항상 AI SDK v4 타입 반환

// Mastra native format (default)
const result = await agent.stream(messages)

표준 API

출력을 선택하려면 format 옵션을 사용하세요.

• 'mastra'(기본)
• 'aisdk'(AI SDK v5 호환)

// AI SDK v5 compatibility
const result = await agent.stream(messages, {
  format: 'aisdk',
})

표준 API의 새로운 옵션

다음 옵션은 표준 .stream() 및 generate()에서는 사용할 수 있지만 레거시 메서드에서는 사용할 수 없습니다.

• format- 'mastra' 또는 'aisdk' 출력 형식 중에서 선택하세요:

  const result = await agent.stream(messages, {
    format: 'aisdk', // or 'mastra' (default)
  })

• system- 사용자 정의 시스템 메시지(지침과 별도)

  const result = await agent.stream(messages, {
    system: 'You are a helpful assistant',
  })

• structuredOutput- Model 재정의 및 사용자 정의 옵션으로 구조화된 출력이 향상되었습니다.

  • jsonPromptInjection- response_format을 Model에 전달하는 기본 동작을 재정의하는 데 사용됩니다. 그러면 Model이 구조화된 출력을 반환하도록 강제하기 위해 Prompt에 컨텍스트가 주입됩니다.

  • model- Model이 추가되면 주 Agent의 응답을 구조화하기 위한 하위 Agent가 생성됩니다. 주 Agent는 Tool을 호출하고 텍스트를 반환하며, 하위 Agent는 제공된 스키마를 준수하는 개체를 반환합니다. 이는 다음을 대체합니다.experimental_output.

  • errorStrategy- 출력이 스키마와 일치하지 않을 때 발생하는 상황을 결정합니다.

    • 'warn' - 경고를 기록합니다.
    • 'error' - 오류 발생
    • 'fallback' - 제공한 대체 값을 반환합니다.

    const result = await agent.generate(messages, {
      structuredOutput: {
        schema: z.object({
          name: z.string(),
          age: z.number(),
        }),
        model: 'openai/gpt-5.6-sol', // Optional model override for structuring
        errorStrategy: 'fallback',
        fallbackValue: { name: 'unknown', age: 0 },
        instructions: 'Extract user information', // Override default structuring instructions
      },
    })

• stopWhen- 유연한 정지 조건(걸음 수, 토큰 제한 등).

  const result = await agent.stream(messages, {
    stopWhen: ({ steps, totalTokens }) => steps >= 5 || totalTokens >= 10000,
  })

• providerOptions- 공급자별 옵션(예: OpenAI별 설정)

  const result = await agent.stream(messages, {
    providerOptions: {
      openai: {
        store: true,
        metadata: { userId: '123' },
      },
    },
  })

• onChunk- 각 스트리밍 청크에 대한 콜백.

  const result = await agent.stream(messages, {
    onChunk: chunk => {
      console.log('Received chunk:', chunk)
    },
  })

• onError- 콜백 오류.

  const result = await agent.stream(messages, {
    onError: error => {
      console.error('Stream error:', error)
    },
  })

• onAbort- 콜백을 중단합니다.

  const result = await agent.stream(messages, {
    onAbort: () => {
      console.log('Stream aborted')
    },
  })

• activeTools- 이 실행에 대해 활성화된 Tool을 지정합니다.

  const result = await agent.stream(messages, {
    activeTools: ['search', 'calculator'], // Only these tools will be available
  })

• abortSignal- 취소를 위한 AbortSignal.

  const controller = new AbortController()
  const result = await agent.stream(messages, {
    abortSignal: controller.signal,
  })
  
  // Later: controller.abort();

• prepareStep- 다단계 실행의 각 단계 전에 콜백합니다.

  const result = await agent.stream(messages, {
    prepareStep: ({ step, state }) => {
      console.log('About to execute step:', step)
      return {/* modified state */}
    },
  })

• requireToolApproval- 모든 Tool 호출에는 승인이 필요합니다.

  const result = await agent.stream(messages, {
    requireToolApproval: true,
  })

이동된 레거시 옵션

• temperature그리고 기타modelSettings.

  통합modelSettings

  const result = await agent.stream(messages, {
    modelSettings: {
      temperature: 0.7,
      maxTokens: 1000,
      topP: 0.9,
    },
  })

• resourceId그리고threadId.

  Memory 개체로 이동되었습니다.

  const result = await agent.stream(messages, {
    memory: {
      resource: 'user-123',
      thread: 'thread-456',
    },
  })

더 이상 사용되지 않거나 제거된 옵션

• experimental_output

  Tool 호출과 객체 반환을 허용하려면 대신 structuredOutput을 사용하세요.

  const result = await agent.generate(messages, {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
      }),
      model: 'openai/gpt-5.6-sol',
    },
  })

• output

  output 속성 대신 structuredOutput을 사용하는 것이 권장됩니다. 동일한 결과를 얻으려면 Model을 생략하고 structuredOutput.schema만 전달하세요. Model이 response_format을 기본적으로 지원하지 않는다면 선택적으로 jsonPromptInjection: true를 추가하세요.

  const result = await agent.generate(messages, {
    structuredOutput: {
      schema: z.object({
        name: z.string(),
      }),
    },
  })

• memoryOptions

  사용memory instead.

  const result = await agent.generate(messages, {
    memory: {},
  })

유형 변경

레거시 API

• CoreMessage[]

자세한 내용은 다음 API 참조를 참조하세요.

• Agent.generateLegacy()

• Agent.streamLegacy() 표준 API

• ModelMessage[]

  toolChoiceAI SDK v5를 사용합니다.ToolChoice type.

  type ToolChoice<TOOLS extends Record<string, unknown>> =
    | 'auto'
    | 'none'
    | 'required'
    | {
        type: 'tool'
        toolName: Extract<keyof TOOLS, string>
      }

자세한 내용은 다음 API 참조를 참조하세요.

• Agent.생성()
• Agent.스트림()