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

# Agent.listSuspendedRuns()

**新增於：** `@mastra/core@1.43.0`

`.listSuspendedRuns()` 方法會從 Workflow 快照儲存空間列出已暫停的 Agent run：包括等待需要[核准](https://mastra.zisheng.pro/zh-TW/docs/agents/agent-approval)之 Tool 呼叫的 run，或等待呼叫了 `suspend()` 之 Tool 的 run。由於探索作業以儲存空間而非記憶體內狀態為依據，因此伺服器重新啟動後仍可運作，也支援多個伺服器執行個體。

將回傳的 `runId` 傳給 [`resumeStream()`](https://mastra.zisheng.pro/zh-TW/docs/agents/agent-approval)、`approveToolCall()` 或 `declineToolCall()`，即可繼續該 run。

篩選條件與 Workflow run 列表 API（`listWorkflowRuns`）相同，另外提供 Agent 層級的 `threadId` 篩選條件。

## 使用範例

探索對話中待處理的 run 並繼續執行。請檢查 `requiresApproval` 以選擇正確的繼續方式：若因等待核准而暫停，請使用 `approveToolCall()` / `declineToolCall()`；若因 `suspend()` 而暫停，請使用帶有恢復資料的 `resumeStream()`：

```typescript
const { runs } = await agent.listSuspendedRuns({
  threadId: 'thread-123',
  resourceId: 'user-456',
})

const run = runs[0]
const toolCall = run?.toolCalls[0]

if (run && toolCall) {
  const stream = toolCall.requiresApproval
    ? await agent.approveToolCall({ runId: run.runId, toolCallId: toolCall.toolCallId })
    : await agent.resumeStream({ name: 'San Francisco' }, { runId: run.runId })
}
```

## 參數

**options** (`AgentListSuspendedRunsOptions`): 用來限定結果範圍的篩選與分頁設定。 (Default: `{}`)

**options.threadId** (`string`): 僅回傳屬於此記憶體 thread 的 run。

**options.resourceId** (`string`): 僅回傳屬於此記憶體 resource 的 run。

**options.fromDate** (`Date`): 僅回傳於此日期當天或之後建立的 run。

**options.toDate** (`Date`): 僅回傳於此日期當天或之前建立的 run。

**options.perPage** (`number`): 每頁項目數。同時提供 perPage 與 page 時會套用分頁；否則會回傳所有符合條件的 run。

**options.page** (`number`): 以零為起始索引的頁碼。

## 回傳值

**result** (`Promise<AgentListSuspendedRunsResult>`): 解析為符合條件之 run 與分頁前總數的 promise。

```typescript
interface AgentListSuspendedRunsResult {
  runs: AgentRun[]
  /** Total number of matching runs, before pagination */
  total: number
}

interface AgentRun {
  /** Run ID accepted by resumeStream(), approveToolCall(), and declineToolCall() */
  runId: string
  status: 'suspended'
  threadId?: string
  resourceId?: string
  /** When the run suspended */
  suspendedAt: Date
  /** Suspended tool calls awaiting approval or resume data */
  toolCalls: AgentRunToolCall[]
}

interface AgentRunToolCall {
  toolCallId?: string
  toolName?: string
  /** Arguments the model supplied (approval suspensions only) */
  args?: unknown
  /** True when the run is waiting on a tool-call approval */
  requiresApproval: boolean
  /** The tool-defined suspend payload when the tool called suspend() */
  suspendPayload?: unknown
}
```

## 探索範圍

結果範圍僅限於由您呼叫 `listSuspendedRuns()` 的 Agent 所啟動之 run：快照會保存擁有該 run 之 Agent 的 id，因此不會回傳同一 Mastra 執行個體中其他 Agent 啟動的 run。在 [supervisor 設定](https://mastra.zisheng.pro/zh-TW/docs/agents/agent-approval)中，supervisor 會看到自己的外層 run（也就是要恢復的 run），而子 Agent 的內層 run 只有該子 Agent 本身可見。您可以依 `threadId` 與 `resourceId` 篩選，將結果限定至單一對話。

run 快照只會在 run 等待輸入時保存，並於 run 完成時刪除，因此只能從儲存空間探索已暫停的 run。只有在 Mastra 執行個體設定了持久化[儲存 Provider](https://mastra.zisheng.pro/zh-TW/docs/storage/overview)時，已暫停的 run 才能在重新啟動後保留。若使用預設的記憶體內儲存空間，重新啟動時快照會遺失。

## 相關內容

- [Agent 核准](https://mastra.zisheng.pro/zh-TW/docs/agents/agent-approval)
- [儲存空間](https://mastra.zisheng.pro/zh-TW/docs/storage/overview)