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

# Agent.streamUntilIdle()

**추가된 항목:** `@mastra/core@1.29.0`

:::warning\[사용되지 않음]

`streamUntilIdle()`은 더 이상 사용되지 않습니다. 대신 `untilIdle` 옵션과 함께 `stream()`을 사용하세요.

```ts
const result = await agent.stream('Research solana for me', {
  untilIdle: true,
  memory: { thread: 't1', resource: 'u1' },
})
```

유휴 시간 제한을 구성하려면 `untilIdle: { maxIdleMs: 60_000 }`을 전달하세요. :::

`streamUntilIdle()`Agent의 응답을 스트리밍하고 실행 중에 전달된 모든 백그라운드 작업이 완료될 때까지 스트림을 열어 둡니다. 작업이 완료되면 해당 결과가 Memory에 기록되고 LLM이 이에 반응할 수 있도록 Agent 루프가 자동으로 다시 시작됩니다. 실행 중인 작업이 없고 대기 중인 완료가 없으면 스트림이 닫힙니다.

Agent가 백그라운드 작업(일반적으로 장기 실행 Tool 또는 하위 Agent)을 디스패치하고 초기 응답과 작업 완료로 트리거되는 **모든** 후속 실행을 아우르는 단일 스트림이 필요할 때 사용합니다. 포그라운드 전용 실행이나 후속 실행을 수동으로 관리하려는 경우(결과를 처리하도록 Agent에 수동으로 Prompt 제공)에는 [`Agent.stream()`](https://mastra.zisheng.pro/ko/reference/streaming/agents/stream)을 사용하세요.

## 사용예

```ts
const stream = await agent.streamUntilIdle('Research solana for me', {
  memory: { thread: 't1', resource: 'u1' },
})

for await (const chunk of stream.fullStream) {
  // chunks from the initial turn AND any continuation turns triggered by
  // background task completions flow through here
}
```

> **정보:** `streamUntilIdle()`에는 [`BackgroundTaskManager`](https://mastra.zisheng.pro/ko/reference/configuration)와 [Memory](https://mastra.zisheng.pro/ko/docs/memory/overview) 백엔드가 모두 필요합니다. 둘 중 하나라도 없으면 일반 `agent.stream()` 호출을 사용합니다.

## 매개변수

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

**options** (`AgentExecutionOptions<Output> & { maxIdleMs?: number }`): Agent.stream()이 허용하는 모든 옵션과 maxIdleMs를 허용합니다. 전체 목록은 Agent.stream() 레퍼런스를 참조하세요.

**options.maxIdleMs** (`number`): 턴 사이에서 이 시간(ms) 동안 유휴 상태가 지속되면 외부 스트림을 닫습니다. 타이머는 래퍼가 턴 사이에 있을 때만 실행되므로 첫 번째 토큰이 느리더라도 스트림이 닫히지 않습니다. 기본값: 5분.

**options.memory** (`{ thread?: string | { id: string }; resource?: string }`): 실행에 사용할 Memory 스레드와 리소스입니다. 후속 실행에서 백그라운드 작업 결과를 대화에 다시 기록하려면 필요합니다.

**options.structuredOutput** (`PublicStructuredOutputOptions<Output>`): 스키마 기반 구조화 출력입니다. Agent.stream()과 동일한 형태입니다. 집계 속성은 첫 번째 턴에 대해서만 이행된다는 점에 유의하세요.

그 밖의 모든 옵션(`maxSteps`, `modelSettings`, `toolChoice`, `outputProcessors`, `onFinish`, `onChunk` 등)은 [`Agent.stream()` 매개변수](https://mastra.zisheng.pro/ko/reference/streaming/agents/stream)를 참조하세요. `streamUntilIdle()`은 이를 초기 턴에 전달합니다.

## 보고

**stream** (`MastraModelOutput<Output>`): fullStream이 초기 턴과 모든 자동 후속 실행을 아우르는 MastraModelOutput입니다. 집계 속성(text, toolCalls, toolResults, finishReason, messageList, getFullOutput())은 첫 번째 턴에 대해서만 이행됩니다.

### 집계 속성에 대한 주의 사항

`streamUntilIdle()`은 첫 번째 턴의 `MastraModelOutput`을 프록시하는 값을 반환합니다. `fullStream`만 모든 후속 실행을 아우르는 결합 스트림으로 대체됩니다. 그 밖의 모든 속성(`text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()`)은 **첫 번째 턴의** 내부 버퍼에 대해서만 이행됩니다. 모든 후속 실행에 대한 집계 보기가 필요하면 `fullStream`을 직접 소비하고 누적하세요.

## 계속 행동

내부적으로는`streamUntilIdle()`:

1. `agent.stream(...)`을 통해 초기 턴을 실행하고 해당 `fullStream`을 외부 스트림으로 파이프합니다.
2. 확인된 Memory 범위의 백그라운드 작업 완료 이벤트를 구독합니다.
3. 각 터미널 이벤트(`background-task-completed`, `background-task-failed`, `background-task-cancelled`)를 큐에 넣고, 외부 래퍼가 턴 사이에서 유휴 상태가 되면 완료된 `toolCallId` 목록을 담은 지시문과 함께 `agent.stream([], ...)`을 다시 호출합니다. 후속 턴은 동일한 외부 스트림으로 흐릅니다.
4. 실행 중인 작업도 대기 중인 완료 이벤트도 없으면 외부 스트림을 닫습니다.

## 확장된 사용 예

### 턴 사이의 유휴 시간 제한

```ts
const stream = await agent.streamUntilIdle('Kick off the long jobs', {
  memory: { thread: 't1', resource: 'u1' },
  maxIdleMs: 60_000, // close the stream after 1 minute of idleness between turns
})

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'background-task-completed') {
    console.log('Task complete:', chunk.payload.taskId)
  }
}
```

### 연속된 내용 전체에서 텍스트 집계

```ts
const stream = await agent.streamUntilIdle('Research and summarize', {
  memory: { thread: 't1', resource: 'u1' },
})

let fullText = ''
for await (const chunk of stream.fullStream) {
  if (chunk.type === 'text-delta') {
    fullText += chunk.payload.text
  }
}
```

## 관련된

- [백그라운드 작업](https://mastra.zisheng.pro/ko/docs/long-running-agents/background-tasks)
- [`Agent.stream()`참조](https://mastra.zisheng.pro/ko/reference/streaming/agents/stream)
- [backgroundTasks 구성 참조](https://mastra.zisheng.pro/ko/reference/configuration)
- [스트림 청크 유형](https://mastra.zisheng.pro/ko/reference/streaming/ChunkType)