KakaFlow KB

Streaming events

5 phút đọc

Streaming events

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Mastra documentation for streaming real-time events from agents or workflows, providing visibility into LLM output generation and workflow execution status for application developers.

Insight

Mastra provides a streaming API via .stream() on agents and workflows that emits real-time events representing different stages of generation and execution. Core agent/workflow event types include: start (marks beginning of a run), step-start (workflow step begins), text-delta (incremental text chunks from LLM), tool-call (agent decides to use a tool with name and arguments), tool-result (result from tool execution), step-finish (step finalizes with metadata like finish reason), and finish (completion with usage statistics). For multi-agent collaboration using agent.network(), additional orchestration events are emitted: routing-agent-start, routing-agent-text-delta, routing-agent-end (with selected primitive and reason), agent-execution-start/end, agent-execution-event-* (delegated agent events), workflow-execution-start/end, workflow-execution-event-* (delegated workflow events), tool-execution-start/end, network-execution-event-step-finish, and network-execution-event-finish. Events always include a type field and can include from (e.g., ‘AGENT’, ‘WORKFLOW’) and payload fields. For workflows using .foreach(), each iteration emits a workflow-step-progress event with id, completedCount, totalCount, currentIndex, iterationStatus (success/failed/suspended), and iterationOutput.

Hành động

Use for await loop to iterate over the stream object returned by .stream(). For agents: call testAgent.stream([{ role: 'user', content: '... }]) and iterate with for await (const chunk of stream). For workflows: call testWorkflow.createRun() then run.stream({ inputData: { value: 'initial data' } }). Each chunk is a JSON-like object with type, optional from, optional runId, and payload containing event-specific data. For foreach progress tracking, check chunk.type === 'workflow-step-progress' and access properties like chunk.payload.completedCount and chunk.payload.iterationStatus. Visit Agent.stream() reference for more information.

Kết quả

Returns real-time event chunks as the agent or workflow executes, including text deltas, tool calls/results, step status, and final usage statistics when complete.

Điều kiện áp dụng

Event types vary depending on whether streaming from an agent or workflow; network events only apply when using agent.network() for multi-agent collaboration.

Nội dung gốc (Original)

Streaming events

Streaming from agents or workflows provides real-time visibility into either the LLM’s output or the status of a workflow run. This feedback can be passed directly to the user, or used within applications to handle workflow status more effectively, creating a smoother and more responsive experience.

Events emitted from agents or workflows represent different stages of generation and execution, such as when a run starts, when text is produced, or when a tool is invoked.

Event types

Below is a complete list of events emitted from .stream(). Depending on whether you’re streaming from an agent or a workflow, only a subset of these events will occur:

  • start: Marks the beginning of an agent or workflow run.
  • step-start: Indicates a workflow step has begun execution.
  • text-delta: Incremental text chunks as they’re generated by the LLM.
  • tool-call: When the agent decides to use a tool, including the tool name and arguments.
  • tool-result: The result returned from tool execution.
  • step-finish: Confirms that a specific step has fully finalized, and may include metadata like the finish reason for that step.
  • finish: When the agent or workflow completes, including usage statistics.

Network event types

When using agent.network() for multi-agent collaboration, additional event types are emitted to track the orchestration flow:

  • routing-agent-start: The routing agent begins analyzing the task to decide which primitive (agent/workflow/tool) to delegate to.
  • routing-agent-text-delta: Incremental text as the routing agent processes the response from the selected primitive.
  • routing-agent-end: The routing agent completes its selection, including the selected primitive and reason for selection.
  • agent-execution-start: A delegated agent begins execution.
  • agent-execution-end: A delegated agent completes execution.
  • agent-execution-event-*: Events from the delegated agent’s execution (e.g., agent-execution-event-text-delta).
  • workflow-execution-start: A delegated workflow begins execution.
  • workflow-execution-end: A delegated workflow completes execution.
  • workflow-execution-event-*: Events from the delegated workflow’s execution.
  • tool-execution-start: A delegated tool begins execution.
  • tool-execution-end: A delegated tool completes execution.
  • network-execution-event-step-finish: A network iteration step completes.
  • network-execution-event-finish: The entire network execution completes.

Inspecting agent streams

Iterate over the stream with a for await loop to inspect all emitted event chunks.

const testAgent = mastra.getAgent('testAgent')
 
const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])
 
for await (const chunk of stream) {
  console.log(chunk)
}

Info: Visit Agent.stream() for more information.

Example agent output

Below is an example of events that may be emitted. Each event always includes a type and can include additional fields like from and payload.

{
  type: 'start',
  from: 'AGENT',
  // ..
}
{
  type: 'step-start',
  from: 'AGENT',
  payload: {
    messageId: 'msg-cdUrkirvXw8A6oE4t5lzDuxi',
    // ...
  }
}
{
  type: 'tool-call',
  from: 'AGENT',
  payload: {
    toolCallId: 'call_jbhi3s1qvR6Aqt9axCfTBMsA',
    toolName: 'testTool'
    // ..
  }
}

Inspecting workflow streams

Iterate over the stream with a for await loop to inspect all emitted event chunks.

const testWorkflow = mastra.getWorkflow('testWorkflow')
 
const run = await testWorkflow.createRun()
 
const stream = await run.stream({
  inputData: {
    value: 'initial data',
  },
})
 
for await (const chunk of stream) {
  console.log(chunk)
}

Example workflow output

Below is an example of events that may be emitted. Each event always includes a type and can include additional fields like from and payload.

{
  type: 'workflow-start',
  runId: '221333ed-d9ee-4737-922b-4ab4d9de73e6',
  from: 'WORKFLOW',
  // ...
}
{
  type: 'workflow-step-start',
  runId: '221333ed-d9ee-4737-922b-4ab4d9de73e6',
  from: 'WORKFLOW',
  payload: {
    stepName: 'step-1',
    args: { value: 'initial data' },
    stepCallId: '9e8c5217-490b-4fe7-8c31-6e2353a3fc98',
    startedAt: 1755269732792,
    status: 'running'
  }
}

Foreach progress events

When a workflow uses .foreach(), each iteration emits a workflow-step-progress event. You can use these to track real-time progress:

for await (const chunk of stream) {
  if (chunk.type === 'workflow-step-progress') {
    console.log(
      `${chunk.payload.id}: ${chunk.payload.completedCount}/${chunk.payload.totalCount} — ${chunk.payload.iterationStatus}`,
    )
  }
}

Each progress event includes:

  • id: The step ID of the foreach step
  • completedCount: Number of iterations completed so far
  • totalCount: Total number of iterations
  • currentIndex: Index of the iteration that completed
  • iterationStatus: Status of the iteration (success, failed, or suspended)
  • iterationOutput: Output of the iteration (when successful)

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược