跳至主要內容

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
只傳回屬於此記憶體執行緒的執行。

resourceId?:

string
只傳回屬於此記憶體資源的執行。

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 啟動的執行。在監督者設定中，監督者會看到其外層執行（即需要恢復的執行），而子 Agent 的內層執行只有該子 Agent 本身可以看到。使用 threadId 和 resourceId 篩選，即可將結果範圍限於單一對話。

執行快照只會在執行等候輸入期間保留，並會在執行完成時刪除，因此只有已暫停的執行可從儲存空間中找到。只有在 Mastra 實例已設定持久性儲存空間 Provider時，已暫停的執行才可在重新啟動後保留。使用預設的記憶體內儲存區時，快照會在重新啟動後遺失。

On this page