Agent.listSuspendedRuns()

Ajouté dans : @mastra/core@1.43.0

La méthode .listSuspendedRuns() répertorie les exécutions d’Agent suspendues à partir du stockage des instantanés de Workflow : exécutions en attente d’un appel de Tool nécessitant une approbation, ou d’un Tool ayant appelé suspend(). Comme la découverte s’appuie sur le stockage plutôt que sur l’état en mémoire, elle fonctionne après le redémarrage du serveur et entre plusieurs instances de serveur.

Transmettez le runId renvoyé à resumeStream(), approveToolCall() ou declineToolCall() pour poursuivre l’exécution.

Le contrat de filtrage reprend celui des API qui répertorient les exécutions de Workflow (listWorkflowRuns), auquel s’ajoute le filtre threadId au niveau de l’Agent.

Exemple d’utilisation

Découvrez l’exécution en attente d’une conversation et poursuivez-la. Vérifiez requiresApproval pour choisir la reprise appropriée : approveToolCall() / declineToolCall() pour les suspensions liées à une approbation, ou resumeStream() avec des données de reprise pour les suspensions fondées sur suspend() :

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 })
}

Paramètres

options?:

AgentListSuspendedRunsOptions

= {}

Filtres et pagination permettant de délimiter les résultats.

AgentListSuspendedRunsOptions

threadId?:

string

Renvoie uniquement les exécutions qui appartiennent à ce fil de discussion de Memory.

resourceId?:

string

Renvoie uniquement les exécutions qui appartiennent à cette ressource de Memory.

fromDate?:

Date

Renvoie uniquement les exécutions créées à cette date ou après celle-ci.

toDate?:

Date

Renvoie uniquement les exécutions créées à cette date ou avant celle-ci.

perPage?:

number

Nombre d’éléments par page. La pagination s’applique lorsque perPage et page sont tous deux fournis ; sinon, toutes les exécutions correspondantes sont renvoyées.

page?:

number

Numéro de page indexé à partir de zéro.

Valeur renvoyée

result:

Promise<AgentListSuspendedRunsResult>

Promesse qui se résout en exécutions correspondantes et en nombre total avant pagination.

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
}

Portée de la découverte

Les résultats se limitent aux exécutions démarrées par l’Agent sur lequel vous appelez listSuspendedRuns() : les instantanés conservent l’ID de l’Agent propriétaire, de sorte que les exécutions démarrées par d’autres Agents sur la même instance Mastra ne sont pas renvoyées. Dans les configurations avec superviseur, le superviseur voit son exécution externe, celle qui doit être reprise, tandis que l’exécution interne d’un sous-Agent n’est visible que depuis ce dernier. Filtrez selon threadId et resourceId pour limiter les résultats à une conversation.

Les instantanés d’exécution ne sont conservés que tant qu’une exécution attend une entrée et sont supprimés lorsqu’elle se termine ; seules les exécutions suspendues peuvent donc être découvertes dans le stockage. Elles ne persistent après un redémarrage que si un fournisseur de stockage persistant est configuré sur l’instance Mastra. Avec le stockage en mémoire par défaut, les instantanés sont perdus au redémarrage.

Voir aussi

• Approbation des Agents
• Storage