Agent.streamLegacy() (레거시)

경고

사용 중단됨: 이 메서드는 사용 중단되었으며 V1 Model에서만 작동합니다. V2 Model의 경우 새로운 .stream() 메서드를 대신 사용하세요. 업그레이드에 대한 자세한 내용은 마이그레이션 가이드를 참조하세요.

.streamLegacy() 메서드는 Agent 스트리밍 API의 레거시 버전으로, V1 Model Agent의 응답을 실시간으로 스트리밍하는 데 사용됩니다. 이 메서드는 메시지와 선택적 스트리밍 옵션을 받습니다.

사용예

await agent.streamLegacy('message for agent')

매개변수

messages:

string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]

Agent에 보낼 메시지입니다. 단일 문자열, 문자열 배열 또는 구조화된 메시지 객체를 사용할 수 있습니다.

options?:

AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>

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

AgentStreamOptions

abortSignal?:

AbortSignal

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

context?:

CoreMessage[]

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

experimental_output?:

Zod schema | JsonSchema7

텍스트 생성 및 Tool 호출과 함께 구조화된 출력을 생성할 수 있게 합니다. Model은 제공된 스키마를 준수하는 응답을 생성합니다.

instructions?:

string

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

output?:

Zod schema | JsonSchema7

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

memory?:

object

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

thread:

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

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

resource:

string

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

options?:

MemoryConfig

메시지 기록 및 의미론적 회상과 같은 Memory 동작 구성입니다.

maxSteps?:

number

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

maxRetries?:

number

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

memoryOptions?:

MemoryConfig

**사용 중단됨.** 대신 memory.options를 사용하세요. Memory 관리를 위한 구성 옵션입니다.

lastMessages?:

number | false

컨텍스트에 포함할 최근 메시지 수입니다. 비활성화하려면 false를 사용합니다.

semanticRecall?:

boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }

관련된 과거 메시지를 찾는 의미론적 회상을 활성화합니다. 불리언 또는 세부 구성으로 지정할 수 있습니다.

workingMemory?:

WorkingMemory

작업 Memory 기능을 위한 구성입니다.

threads?:

{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }

자동 제목 생성을 포함한 스레드별 구성입니다.

onFinish?:

StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>

스트리밍이 완료될 때 호출되는 콜백 함수입니다. 최종 결과를 받습니다.

onStepFinish?:

StreamTextOnStepFinishCallback<any> | never

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

resourceId?:

string

**사용 중단됨.** 대신 memory.resource를 사용하세요. Agent와 상호작용하는 사용자 또는 리소스의 식별자입니다. threadId가 제공되면 반드시 제공해야 합니다.

telemetry?:

TelemetrySettings

스트리밍 중 텔레메트리 수집 설정입니다.

isEnabled?:

boolean

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

recordInputs?:

boolean

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

recordOutputs?:

boolean

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

functionId?:

string

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

temperature?:

number

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

threadId?:

string

**사용 중단됨.** 대신 memory.thread를 사용하세요. 대화 스레드의 식별자입니다. 여러 상호작용에서 컨텍스트를 유지할 수 있게 합니다. resourceId가 제공되면 반드시 제공해야 합니다.

toolChoice?:

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

스트리밍 중 Agent가 Tool을 사용하는 방식을 제어합니다.

'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).

providerOptions?:

Record<string, Record<string, JSONValue>>

기반 LLM Provider에 그대로 전달되는 추가 Provider별 옵션입니다. 구조는 { providerName: { optionKey: value } }입니다. 예: { openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }.

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별 옵션 레코드입니다.

runId?:

string

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

requestContext?:

RequestContext

의존성 주입 및 컨텍스트 정보를 위한 요청 컨텍스트입니다.

maxTokens?:

number

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

topP?:

number

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

topK?:

number

각 후속 토큰에서 상위 K개 선택지만 샘플링합니다. 확률이 낮은 '롱테일' 응답을 제거하는 데 사용됩니다.

presencePenalty?:

number

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

frequencyPenalty?:

number

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

stopSequences?:

string[]

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

seed?:

number

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

headers?:

Record<string, string | undefined>

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

보고

textStream?:

AsyncGenerator<string>

텍스트 청크가 제공되는 대로 산출하는 비동기 제너레이터입니다.

fullStream?:

Promise<ReadableStream>

전체 응답의 ReadableStream으로 이행되는 Promise입니다.

text?:

Promise<string>

전체 텍스트 응답으로 이행되는 Promise입니다.

usage?:

Promise<{ totalTokens: number; promptTokens: number; completionTokens: number }>

토큰 사용량 정보로 이행되는 Promise입니다.

finishReason?:

Promise<string>

스트림이 종료된 이유로 이행되는 Promise입니다.

toolCalls?:

Promise<Array<ToolCall>>

스트리밍 과정에서 이루어진 Tool 호출로 이행되는 Promise입니다.

toolName:

string

호출된 Tool의 이름입니다.

args:

any

Tool에 전달된 인수입니다.

확장된 사용 예

await agent.streamLegacy('message for agent', {
  temperature: 0.7,
  maxSteps: 3,
  memory: {
    thread: 'user-123',
    resource: 'test-app',
  },
  toolChoice: 'auto',
})

새로운 API로 마이그레이션

정보

새로운 .stream() 메서드는 AI SDK v5+ 호환성, 향상된 구조화 출력 처리, 개선된 콜백 시스템을 비롯한 확장된 기능을 제공합니다. 자세한 마이그레이션 지침은 마이그레이션 가이드를 참조하세요.

빠른 마이그레이션 예

이전(레거시)

const result = await agent.streamLegacy('message', {
  temperature: 0.7,
  maxSteps: 3,
  onFinish: result => console.log(result),
})

이후(새 API)

const result = await agent.stream('message', {
  modelSettings: {
    temperature: 0.7,
  },
  maxSteps: 3,
  onFinish: result => console.log(result),
})

관련된

• 마이그레이션 가이드
• 새로운 .stream() 메소드
• 응답 생성
• 스트리밍 응답