跳到主要内容

Agent.listSuspendedRuns()

添加于： @mastra/core@1.43.0

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

将返回的 runId 传给 resumeStream()、approveToolCall() 或 declineToolCall() 以继续运行。

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

使用示例
使用示例的直接链接

查找某个对话中待处理的运行并继续执行。检查 requiresApproval 以选择正确的继续方式：对于审批导致的暂停，使用 approveToolCall() / declineToolCall()；对于基于 suspend() 的暂停，使用带恢复数据的 resumeStream()：

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
= {}
用于限定结果范围的筛选和分页选项。
AgentListSuspendedRunsOptions

threadId?:

string
仅返回属于此 memory thread 的运行。

resourceId?:

string
仅返回属于此 memory resource 的运行。

fromDate?:

Date
仅返回在此日期或之后创建的运行。

toDate?:

Date
仅返回在此日期或之前创建的运行。

perPage?:

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

page?:

number
从零开始的页码。

返回值
返回值的直接链接

result:

Promise<AgentListSuspendedRunsResult>
一个 Promise，解析为匹配的运行以及分页前的总数。
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 配置中，supervisor 会看到其外层运行（即需要恢复的运行），而 subagent 的内层运行只能从该 subagent 本身看到。使用 threadId 和 resourceId 筛选，可将结果限定到一个对话。

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

On this page