跳至主要內容

Agent.listSuspendedRuns()

新增於： @mastra/core@1.43.0

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

將回傳的 runId 傳給 resumeStream()、approveToolCall() 或 declineToolCall()，即可繼續該 run。

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

使用範例
「使用範例」的直接連結

探索對話中待處理的 run 並繼續執行。請檢查 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
僅回傳屬於此記憶體 thread 的 run。

resourceId?:

string
僅回傳屬於此記憶體 resource 的 run。

fromDate?:

Date
僅回傳於此日期當天或之後建立的 run。

toDate?:

Date
僅回傳於此日期當天或之前建立的 run。

perPage?:

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

page?:

number
以零為起始索引的頁碼。

回傳值
「回傳值」的直接連結

result:

Promise<AgentListSuspendedRunsResult>
解析為符合條件之 run 與分頁前總數的 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 所啟動之 run：快照會保存擁有該 run 之 Agent 的 id，因此不會回傳同一 Mastra 執行個體中其他 Agent 啟動的 run。在 supervisor 設定中，supervisor 會看到自己的外層 run（也就是要恢復的 run），而子 Agent 的內層 run 只有該子 Agent 本身可見。您可以依 threadId 與 resourceId 篩選，將結果限定至單一對話。

run 快照只會在 run 等待輸入時保存，並於 run 完成時刪除，因此只能從儲存空間探索已暫停的 run。只有在 Mastra 執行個體設定了持久化儲存 Provider時，已暫停的 run 才能在重新啟動後保留。若使用預設的記憶體內儲存空間，重新啟動時快照會遺失。

On this page