# 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.

```typescript
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);
}
```

Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream/llms.txt) 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`.

```typescript
{
  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.

```typescript
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`.

```typescript
{
  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'
  }
}
```

## Inspecting agent networks

When using multi-agent collaboration with `agent.network()`, iterate over the stream to track how tasks are delegated and executed across agents, workflows, and tools.

```typescript
const networkAgent = mastra.getAgent("networkAgent");

const networkStream = await networkAgent.network(
  "Research dolphins then write a report",
);

for await (const chunk of networkStream) {
  console.log(chunk);
}
```

Visit [Agent.network()](https://mastra.ai/reference/agents/network/llms.txt) for more information.

### Example network output

Network streams emit events that track the orchestration flow. Each iteration begins with routing, followed by execution of the selected primitive.

```typescript
// Routing agent decides what to do
{
  type: 'routing-agent-start',
  from: 'NETWORK',
  runId: '7a3b9c2d-1e4f-5a6b-8c9d-0e1f2a3b4c5d',
  payload: {
    agentId: 'routing-agent',
    // ...
  }
}
// Routing agent makes a selection
{
  type: 'routing-agent-end',
  from: 'NETWORK',
  runId: '7a3b9c2d-1e4f-5a6b-8c9d-0e1f2a3b4c5d',
  payload: {
    // ...
  }
}
// Delegated agent begins execution
{
  type: 'agent-execution-start',
  from: 'NETWORK',
  runId: '8b4c0d3e-2f5a-6b7c-9d0e-1f2a3b4c5d6e',
  payload: {
    // ...
  }
}
// Events from the delegated agent's execution
{
  type: 'agent-execution-event-text-delta',
  from: 'NETWORK',
  runId: '8b4c0d3e-2f5a-6b7c-9d0e-1f2a3b4c5d6e',
  payload: {
    type: 'text-delta',
    payload: {
      // ...
    }
  }
}
```

### Filtering network events

You can filter events by type to track specific aspects of the network execution:

```typescript
const networkStream = await networkAgent.network(
  "Analyze data and create visualization",
);

for await (const chunk of networkStream) {
  // Track routing decisions
  if (chunk.type === "routing-agent-end") {
    console.log(
      "Selected:",
      chunk.payload.resourceType,
      chunk.payload.resourceId,
    );
    console.log("Reason:", chunk.payload.selectionReason);
  }

  // Track agent delegations
  if (chunk.type === "agent-execution-start") {
    console.log("Delegating to agent:", chunk.payload.agentId);
  }

  // Track workflow delegations
  if (chunk.type === "workflow-execution-start") {
    console.log("Executing workflow:", chunk.payload.name);
  }
}
```