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

# Agent.listSuspendedRuns()

**添加于：** `@mastra/core@1.43.0`

`.listSuspendedRuns()` 方法从 Workflow 快照存储中列出已暂停的 Agent 运行：这些运行可能正在等待需要[审批](https://mastra.zisheng.pro/docs/agents/agent-approval)的 Tool 调用，也可能正在等待调用了 `suspend()` 的 Tool。由于发现机制基于存储而非内存状态，因此它在服务器重启后以及跨多个服务器实例时仍然有效。

将返回的 `runId` 传给 [`resumeStream()`](https://mastra.zisheng.pro/docs/agents/agent-approval)、`approveToolCall()` 或 `declineToolCall()` 以继续运行。

筛选器约定与 Workflow 运行列表 API（`listWorkflowRuns`）一致，并额外提供 Agent 级 `threadId` 筛选器。

## 使用示例

查找某个对话中待处理的运行并继续执行。检查 `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`): 仅返回属于此 memory thread 的运行。

**options.resourceId** (`string`): 仅返回属于此 memory resource 的运行。

**options.fromDate** (`Date`): 仅返回在此日期或之后创建的运行。

**options.toDate** (`Date`): 仅返回在此日期或之前创建的运行。

**options.perPage** (`number`): 每页的条目数。同时提供 perPage 和 page 时应用分页；否则返回所有匹配的运行。

**options.page** (`number`): 从零开始的页码。

## 返回值

**result** (`Promise<AgentListSuspendedRunsResult>`): 一个 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 启动的运行：快照会持久化所属 Agent 的 id，因此不会返回由同一 Mastra 实例中其他 Agent 启动的运行。在 [supervisor 配置](https://mastra.zisheng.pro/docs/agents/agent-approval)中，supervisor 会看到其外层运行（即需要恢复的运行），而 subagent 的内层运行只能从该 subagent 本身看到。使用 `threadId` 和 `resourceId` 筛选，可将结果限定到一个对话。

运行快照仅在运行等待输入期间持久化，并在运行完成时删除，因此从存储中只能发现已暂停的运行。只有当 Mastra 实例配置了持久化[存储 Provider](https://mastra.zisheng.pro/docs/storage/overview)时，已暂停的运行才能在重启后保留。使用默认的内存存储时，快照会在重启时丢失。

## 相关内容

- [Agent 审批](https://mastra.zisheng.pro/docs/agents/agent-approval)
- [存储](https://mastra.zisheng.pro/docs/storage/overview)