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

# Agent.streamLegacy() (레거시)

> **경고:** **사용 중단됨**: 이 메서드는 사용 중단되었으며 V1 Model에서만 작동합니다. V2 Model의 경우 새로운 [`.stream()`](https://mastra.zisheng.pro/ko/reference/streaming/agents/stream) 메서드를 대신 사용하세요. 업그레이드에 대한 자세한 내용은 [마이그레이션 가이드](https://mastra.zisheng.pro/ko/guides/migrations/vnext-to-standard-apis)를 참조하세요.

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

## 사용예

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

## 매개변수

**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): Agent에 보낼 메시지입니다. 단일 문자열, 문자열 배열 또는 구조화된 메시지 객체를 사용할 수 있습니다.

**options** (`AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>`): 스트리밍 프로세스를 위한 선택적 구성입니다.

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

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

**options.experimental\_output** (`Zod schema | JsonSchema7`): 텍스트 생성 및 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 동작 구성입니다.

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

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

**options.memoryOptions** (`MemoryConfig`): \*\*사용 중단됨.\*\* 대신 memory.options를 사용하세요. Memory 관리를 위한 구성 옵션입니다.

**options.memoryOptions.lastMessages** (`number | false`): 컨텍스트에 포함할 최근 메시지 수입니다. 비활성화하려면 false를 사용합니다.

**options.memoryOptions.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): 관련된 과거 메시지를 찾는 의미론적 회상을 활성화합니다. 불리언 또는 세부 구성으로 지정할 수 있습니다.

**options.memoryOptions.workingMemory** (`WorkingMemory`): 작업 Memory 기능을 위한 구성입니다.

**options.memoryOptions.threads** (`{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }`): 자동 제목 생성을 포함한 스레드별 구성입니다.

**options.onFinish** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): 스트리밍이 완료될 때 호출되는 콜백 함수입니다. 최종 결과를 받습니다.

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

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

**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.threadId** (`string`): \*\*사용 중단됨.\*\* 대신 memory.thread를 사용하세요. 대화 스레드의 식별자입니다. 여러 상호작용에서 컨텍스트를 유지할 수 있게 합니다. resourceId가 제공되면 반드시 제공해야 합니다.

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

**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): 기반 LLM Provider에 그대로 전달되는 추가 Provider별 옵션입니다. 구조는 { providerName: { optionKey: value } }입니다. 예: { openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }.

**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.runId** (`string`): 이 생성 실행의 고유 ID입니다. 추적 및 디버깅에 유용합니다.

**options.requestContext** (`RequestContext`): 의존성 주입 및 컨텍스트 정보를 위한 요청 컨텍스트입니다.

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

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

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

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

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

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

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

**options.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입니다.

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

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

## 확장된 사용 예

```typescript
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+ 호환성, 향상된 구조화 출력 처리, 개선된 콜백 시스템을 비롯한 확장된 기능을 제공합니다. 자세한 마이그레이션 지침은 [마이그레이션 가이드](https://mastra.zisheng.pro/ko/guides/migrations/vnext-to-standard-apis)를 참조하세요.

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

#### 이전(레거시)

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

#### 이후(새 API)

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

## 관련된

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