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

# Agent.streamUntilIdle()

**加入版本：** `@mastra/core@1.29.0`

> **已棄用:** `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 的回應，並讓串流保持開啟，直至該次 run 期間分派的每個背景任務都完成。任務完成時，其結果會寫入記憶體，而 agentic loop 會自動重新進入，讓 LLM 可以作出回應。當沒有任務正在執行，亦沒有已排隊的完成事件時，串流便會關閉。

當 Agent 會分派背景任務（一般是長時間執行的 Tool 或子代理），而你希望單一串流涵蓋初始回應以及每個任務完成後觸發的所有後續執行時，可使用此方法。若 run 只包含前景操作，或你希望手動管理後續執行（手動提示 Agent 處理結果），請使用 [`Agent.stream()`](https://mastra.zisheng.pro/zh-HK/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/zh-HK/reference/configuration) 及[記憶體](https://mastra.zisheng.pro/zh-HK/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`): 各 turn 之間閒置達此毫秒數後，關閉外層串流。計時器只會在 wrapper 處於各 turn 之間時運作，因此第一個 token 較慢亦不會關閉串流。預設值：5 分鐘。

**options.memory** (`{ thread?: string | { id: string }; resource?: string }`): 此 run 的記憶體 thread 及 resource。後續執行必須使用此選項，才能將背景任務結果寫回對話。

**options.structuredOutput** (`PublicStructuredOutputOptions<Output>`): 以 schema 為基礎的結構化輸出，格式與 Agent.stream() 相同。請注意，彙總屬性只會根據第一個 turn 解析。

其他所有選項（`maxSteps`、`modelSettings`、`toolChoice`、`outputProcessors`、`onFinish`、`onChunk` 等）請參閱 [`Agent.stream()` 參數](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/stream)。`streamUntilIdle()` 會將它們轉交給初始 turn。

## 傳回值

**stream** (`MastraModelOutput<Output>`): 一個 MastraModelOutput，其 fullStream 涵蓋初始 turn 及每個自動後續執行。彙總屬性（text、toolCalls、toolResults、finishReason、messageList、getFullOutput()）只會根據第一個 turn 解析。

### 彙總屬性的注意事項

`streamUntilIdle()` 會傳回第一個 turn 的 `MastraModelOutput` proxy。只有 `fullStream` 會被替換為涵蓋每個後續執行的合併串流。所有其他屬性（`text`、`toolCalls`、`toolResults`、`finishReason`、`messageList` 及 `getFullOutput()`）均會根據**第一個 turn** 的內部 buffer 解析。

如需所有後續執行的彙總檢視，請自行取用 `fullStream` 並累積資料。

## 後續執行行為

在內部，`streamUntilIdle()` 會：

1. 透過 `agent.stream(...)` 執行初始 turn，並將其 `fullStream` 傳送至外層串流。
2. 訂閱已解析記憶體範圍的背景任務完成事件。
3. 將每個終止事件（`background-task-completed`、`background-task-failed`、`background-task-cancelled`）排入佇列；當外層 wrapper 在各 turn 之間閒置時，以列出已完成 `toolCallId` 的指示再次叫用 `agent.stream([], ...)`。後續 turn 會流入同一個外層串流。
4. 當沒有任務正在執行，亦沒有已排隊的完成事件時，關閉外層串流。

## 延伸使用範例

### 限制各 turn 之間的閒置時間

```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/zh-HK/docs/long-running-agents/background-tasks)
- [`Agent.stream()` 參考](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/stream)
- [backgroundTasks 配置參考](https://mastra.zisheng.pro/zh-HK/reference/configuration)
- [串流 chunk 類型](https://mastra.zisheng.pro/zh-HK/reference/streaming/ChunkType)