Agent.listSuspendedRuns()

추가된 항목: @mastra/core@1.43.0

.listSuspendedRuns() 메서드는 Workflow 스냅샷 스토리지에서 일시 중단된 Agent 실행을 나열합니다. 여기에는 승인이 필요한 Tool 호출을 기다리는 실행이나 suspend()를 호출한 Tool에서 대기 중인 실행이 포함됩니다. 검색은 Memory 내 상태가 아니라 스토리지를 기반으로 하므로 서버를 다시 시작한 후에도 여러 서버 인스턴스에서 작동합니다. 반환된 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 스레드에 속한 실행만 반환합니다.

resourceId?:

string

이 Memory 리소스에 속한 실행만 반환합니다.

fromDate?:

Date

이 날짜 이후 또는 당일에 생성된 실행만 반환합니다.

toDate?:

Date

이 날짜 이전 또는 당일에 생성된 실행만 반환합니다.

perPage?:

number

페이지당 항목 수입니다. perPage와 page가 모두 제공되면 페이지네이션을 적용하고, 그렇지 않으면 일치하는 모든 실행을 반환합니다.

page?:

number

0부터 시작하는 페이지 번호입니다.

보고

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
}

발견 범위

결과 범위는 호출한 Agent가 시작한 실행으로 제한됩니다. listSuspendedRuns()의 경우 스냅샷에 소유 Agent의 ID가 유지되므로, 동일한 Mastra 인스턴스에 있는 다른 Agent가 시작한 실행은 반환되지 않습니다. 감독자 구성에서 감독자는 재개할 대상인 자신의 외부 실행을 확인할 수 있지만, 하위 Agent의 내부 실행은 해당 하위 Agent에서만 확인할 수 있습니다. 결과 범위를 하나의 대화로 제한하려면 threadId와 resourceId로 필터링하세요. 실행 스냅샷은 실행이 입력을 기다리는 동안에만 유지되고 완료되면 삭제됩니다. 따라서 스토리지에서 검색할 수 있는 실행은 일시 중단된 실행뿐입니다. Mastra 인스턴스에 영구 스토리지 Provider가 구성된 경우에만 일시 중단된 실행이 재시작 후에도 유지됩니다. 기본 인메모리 스토어를 사용하면 재시작 시 스냅샷이 손실됩니다.

관련된

• 대리인 승인
• 저장