Agent.streamUntilIdle()

Ajouté dans : @mastra/core@1.29.0

Obsolète

streamUntilIdle() est obsolète. Utilisez plutôt stream() avec l’option untilIdle :

const result = await agent.stream('Research solana for me', {
  untilIdle: true,
  memory: { thread: 't1', resource: 'u1' },
})

Transmettez untilIdle: { maxIdleMs: 60_000 } pour configurer le délai d’expiration en cas d’inactivité.

streamUntilIdle() diffuse la réponse d’un Agent et maintient le flux ouvert jusqu’à la fin de toutes les tâches d’arrière-plan lancées pendant l’exécution. Lorsqu’une tâche se termine, son résultat est écrit dans la mémoire et la boucle agentique reprend automatiquement afin que le LLM puisse y réagir. Le flux se ferme dès qu’aucune tâche n’est en cours d’exécution et qu’aucune fin de tâche n’est en attente.

Utilisez cette méthode lorsque l’Agent lance des tâches d’arrière-plan, généralement des Tools de longue durée ou des sous-Agents, et que vous souhaitez disposer d’un flux unique couvrant la réponse initiale ainsi que toutes les continuations déclenchées par la fin d’une tâche. Pour les exécutions au premier plan uniquement, ou si vous préférez gérer la continuation manuellement en demandant explicitement à l’Agent de traiter le résultat, utilisez Agent.stream().

Exemple d’utilisation

const stream = await agent.streamUntilIdle('Research solana for me', {
  memory: { thread: 't1', resource: 'u1' },
})

for await (const chunk of stream.fullStream) {
  // chunks from the initial turn AND any continuation turns triggered by
  // background task completions flow through here
}

info

streamUntilIdle() nécessite à la fois un BackgroundTaskManager et un backend de mémoire. Si l’un des deux manque, la méthode effectue un simple appel à agent.stream().

Paramètres

messages:

string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]

Messages à envoyer à l’Agent. Il peut s’agir d’une chaîne unique, d’un tableau de chaînes ou d’objets de message structurés.

options?:

AgentExecutionOptions<Output> & { maxIdleMs?: number }

Accepte toutes les options prises en charge par Agent.stream(), ainsi que maxIdleMs. Consultez la référence d’Agent.stream() pour obtenir la liste complète.

maxIdleMs?:

number

Ferme le flux externe après ce nombre de millisecondes d’inactivité entre deux tours. Le minuteur ne s’exécute que lorsque le wrapper se trouve entre deux tours : un premier token lent ne ferme donc pas le flux. Valeur par défaut : 5 minutes.

memory?:

{ thread?: string | { id: string }; resource?: string }

Fil de mémoire et ressource de l’exécution. Requis pour que les continuations puissent réécrire dans la conversation les résultats des tâches d’arrière-plan.

structuredOutput?:

PublicStructuredOutputOptions<Output>

Sortie structurée fondée sur un schéma. Utilise la même structure qu’Agent.stream(). Notez que les propriétés agrégées ne sont résolues que par rapport au premier tour.

Pour toutes les autres options (maxSteps, modelSettings, toolChoice, outputProcessors, onFinish, onChunk, etc.), consultez les paramètres d’Agent.stream(). streamUntilIdle() les transmet au tour initial.

Valeur renvoyée

stream:

MastraModelOutput<Output>

MastraModelOutput dont fullStream couvre le tour initial et toutes les continuations automatiques. Les propriétés agrégées (text, toolCalls, toolResults, finishReason, messageList, getFullOutput()) ne sont résolues que par rapport au premier tour.

Limite des propriétés agrégées

streamUntilIdle() renvoie un proxy autour du MastraModelOutput du premier tour. Seul fullStream est remplacé par un flux combiné couvrant toutes les continuations. Toutes les autres propriétés (text, toolCalls, toolResults, finishReason, messageList et getFullOutput()) sont résolues par rapport au tampon interne du premier tour.

Si vous avez besoin d’une vue agrégée de toutes les continuations, consommez vous-même fullStream et cumulez les données.

Comportement des continuations

En interne, streamUntilIdle() :

1. Exécute le tour initial au moyen d’agent.stream(...) et redirige son fullStream vers le flux externe.
2. S’abonne aux événements de fin des tâches d’arrière-plan pour la portée de mémoire résolue.
3. Place dans une file d’attente chaque événement terminal (background-task-completed, background-task-failed, background-task-cancelled) et, lorsque le wrapper externe est inactif entre deux tours, appelle de nouveau agent.stream([], ...) avec une directive répertoriant les toolCallId terminés. Le tour de continuation est diffusé dans le même flux externe.
4. Ferme le flux externe lorsqu’aucune tâche n’est en cours d’exécution et qu’aucune fin de tâche n’est en attente.

Exemple d’utilisation avancée

Limiter la durée d’inactivité entre deux tours

index.ts

const stream = await agent.streamUntilIdle('Kick off the long jobs', {
  memory: { thread: 't1', resource: 'u1' },
  maxIdleMs: 60_000, // close the stream after 1 minute of idleness between turns
})

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'background-task-completed') {
    console.log('Task complete:', chunk.payload.taskId)
  }
}

Agréger le texte de toutes les continuations

index.ts

const stream = await agent.streamUntilIdle('Research and summarize', {
  memory: { thread: 't1', resource: 'u1' },
})

let fullText = ''
for await (const chunk of stream.fullStream) {
  if (chunk.type === 'text-delta') {
    fullText += chunk.payload.text
  }
}

Voir aussi

• Tâches d’arrière-plan
• Référence d’Agent.stream()
• Référence de la configuration backgroundTasks
• Types de segments de flux