@mastra/core 1.2.0 → 1.2.1-alpha.0

package/dist/docs/streaming/04-reference.md

@@ -1,724 +0,0 @@
-# Streaming API Reference
-
-> API reference for streaming - 7 entries
-
-
----
-
-## Reference: ChunkType
-
-> Documentation for the ChunkType type used in Mastra streaming responses, defining all possible chunk types and their payloads.
-
-The `ChunkType` type defines the mastra format of stream chunks that can be emitted during streaming responses from agents.
-
-## Base Properties
-
-All chunks include these base properties:
-
-## Text Chunks
-
-### text-start
-
-Signals the beginning of text generation.
-
-### text-delta
-
-Incremental text content during generation.
-
-### text-end
-
-Signals the end of text generation.
-
-## Reasoning Chunks
-
-### reasoning-start
-
-Signals the beginning of reasoning generation (for models that support reasoning).
-
-### reasoning-delta
-
-Incremental reasoning text during generation.
-
-### reasoning-end
-
-Signals the end of reasoning generation.
-
-### reasoning-signature
-
-Contains the reasoning signature from models that support advanced reasoning (like OpenAI's o1 series). The signature represents metadata about the model's internal reasoning process, such as effort level or reasoning approach, but not the actual reasoning content itself.
-
-## Tool Chunks
-
-### tool-call
-
-A tool is being called.
-
-### tool-result
-
-Result from a tool execution.
-
-### tool-call-input-streaming-start
-
-Signals the start of streaming tool call arguments.
-
-### tool-call-delta
-
-Incremental tool call arguments during streaming.
-
-### tool-call-input-streaming-end
-
-Signals the end of streaming tool call arguments.
-
-### tool-error
-
-An error occurred during tool execution.
-
-## Source and File Chunks
-
-### source
-
-Contains source information for content.
-
-### file
-
-Contains file data.
-
-## Control Chunks
-
-### start
-
-Signals the start of streaming.
-
-### step-start
-
-Signals the start of a processing step.
-
-### step-finish
-
-Signals the completion of a processing step.
-
-### raw
-
-Contains raw data from the provider.
-
-### finish
-
-Stream has completed successfully.
-
-### error
-
-An error occurred during streaming.
-
-### abort
-
-Stream was aborted.
-
-## Object and Output Chunks
-
-### object
-
-Emitted when using output generation with defined schemas. Contains partial or complete structured data that conforms to the specified Zod or JSON schema. This chunk is typically skipped in some execution contexts and used for streaming structured object generation.
-
-### tool-output
-
-Contains output from agent or workflow execution, particularly used for tracking usage statistics and completion events. Often wraps other chunk types (like finish chunks) to provide nested execution context.
-
-### step-output
-
-Contains output from workflow step execution, used primarily for usage tracking and step completion events. Similar to tool-output but specifically for individual workflow steps.
-
-## Metadata and Special Chunks
-
-### response-metadata
-
-Contains metadata about the LLM provider's response. Emitted by some providers after text generation to provide additional context like model ID, timestamps, and response headers. This chunk is used internally for state tracking and doesn't affect message assembly.
-
-### watch
-
-Contains monitoring and observability data from agent execution. Can include workflow state information, execution progress, or other runtime details depending on the context where `stream()` is used.
-
-### tripwire
-
-Emitted when the stream is forcibly terminated due to content being blocked by a processor. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed. The payload includes information about why the content was blocked and whether a retry was requested.
-
-## Usage Example
-
-```typescript
-const stream = await agent.stream("Hello");
-
-for await (const chunk of stream.fullStream) {
-  switch (chunk.type) {
-    case "text-delta":
-      console.log("Text:", chunk.payload.text);
-      break;
-
-    case "tool-call":
-      console.log("Calling tool:", chunk.payload.toolName);
-      break;
-
-    case "tool-result":
-      console.log("Tool result:", chunk.payload.result);
-      break;
-
-    case "reasoning-delta":
-      console.log("Reasoning:", chunk.payload.text);
-      break;
-
-    case "finish":
-      console.log("Finished:", chunk.payload.stepResult.reason);
-      console.log("Usage:", chunk.payload.output.usage);
-      break;
-
-    case "error":
-      console.error("Error:", chunk.payload.error);
-      break;
-  }
-}
-```
-
-## Related Types
-
-- [.stream()](./agents/stream) - Method that returns streams emitting these chunks
-- [MastraModelOutput](./agents/MastraModelOutput) - The stream object that emits these chunks
-- [workflow.stream()](./workflows/stream) - Method that returns streams emitting these chunks for workflows
-
----
-
-## Reference: MastraModelOutput
-
-> Complete reference for MastraModelOutput - the stream object returned by agent.stream() with streaming and promise-based access to model outputs.
-
-The `MastraModelOutput` class is returned by [.stream()](./stream) and provides both streaming and promise-based access to model outputs. It supports structured output generation, tool calls, reasoning, and comprehensive usage tracking.
-
-```typescript
-// MastraModelOutput is returned by agent.stream()
-const stream = await agent.stream("Hello world");
-```
-
-For setup and basic usage, see the [.stream()](./stream) method documentation.
-
-## Streaming Properties
-
-These properties provide real-time access to model outputs as they're generated:
-
-## Promise-based Properties
-
-These properties resolve to final values after the stream completes:
-
-## Error Properties
-
-## Methods
-
-## Usage Examples
-
-### Basic Text Streaming
-
-```typescript
-const stream = await agent.stream("Write a haiku");
-
-// Stream text as it's generated
-for await (const text of stream.textStream) {
-  process.stdout.write(text);
-}
-
-// Or get the complete text
-const fullText = await stream.text;
-console.log(fullText);
-```
-
-### Structured Output Streaming
-
-```typescript
-const stream = await agent.stream("Generate user data", {
-  structuredOutput: {
-    schema: z.object({
-      name: z.string(),
-      age: z.number(),
-      email: z.string(),
-    }),
-  },
-});
-
-// Stream partial objects
-for await (const partial of stream.objectStream) {
-  console.log("Progress:", partial); // { name: "John" }, { name: "John", age: 30 }, ...
-}
-
-// Get final validated object
-const user = await stream.object;
-console.log("Final:", user); // { name: "John", age: 30, email: "john@example.com" }
-```
-
-````
-
-### Tool Calls and Results
-
-```typescript
-const stream = await agent.stream("What's the weather in NYC?", {
-  tools: { weather: weatherTool }
-});
-
-// Monitor tool calls
-const toolCalls = await stream.toolCalls;
-const toolResults = await stream.toolResults;
-
-console.log("Tools called:", toolCalls);
-console.log("Results:", toolResults);
-````
-
-### Complete Output Access
-
-```typescript
-const stream = await agent.stream("Analyze this data");
-
-const output = await stream.getFullOutput();
-console.log({
-  text: output.text,
-  usage: output.usage,
-  reasoning: output.reasoning,
-  finishReason: output.finishReason,
-});
-```
-
-### Full Stream Processing
-
-```typescript
-const stream = await agent.stream("Complex task");
-
-for await (const chunk of stream.fullStream) {
-  switch (chunk.type) {
-    case "text-delta":
-      process.stdout.write(chunk.payload.text);
-      break;
-    case "tool-call":
-      console.log(`Calling $...`);
-      break;
-    case "reasoning-delta":
-      console.log(`Reasoning: $`);
-      break;
-    case "finish":
-      console.log(`Done! Reason: $`);
-      // Access response messages with any metadata added by output processors
-      const uiMessages = chunk.payload.response?.uiMessages;
-      if (uiMessages) {
-        console.log("Response messages:", uiMessages);
-      }
-      break;
-  }
-}
-```
-
-### Error Handling
-
-```typescript
-const stream = await agent.stream("Analyze this data");
-
-try {
-  // Option 1: Handle errors in consumeStream
-  await stream.consumeStream({
-    onError: (error) => {
-      console.error("Stream error:", error);
-    },
-  });
-
-  const result = await stream.text;
-} catch (error) {
-  console.error("Failed to get result:", error);
-}
-
-// Option 2: Check error property
-const result = await stream.getFullOutput();
-if (stream.error) {
-  console.error("Stream had errors:", stream.error);
-}
-```
-
-## Related Types
-
-- [.stream()](./stream) - Method that returns MastraModelOutput
-- [ChunkType](../ChunkType) - All possible chunk types in the full stream
-
----
-
-## Reference: Run.observeStream()
-
-> Documentation for the `Run.observeStream()` method in workflows, which enables reopening the stream of an already active workflow run.
-
-The `.observeStream()` method opens a new `ReadableStream` to a workflow run that is currently running, allowing you to observe the stream of events if the original stream is no longer available.
-
-## Usage example
-
-```typescript
-const run = await workflow.createRun();
-
-run.stream({
-  inputData: {
-    value: "initial data",
-  },
-});
-
-const stream = await run.observeStream();
-
-for await (const chunk of stream) {
-  console.log(chunk);
-}
-```
-
-## Returns
-
-`ReadableStream<ChunkType>`
-
-## Stream Events
-
-The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
-
-- **`workflow-start`**: Workflow execution begins
-- **`workflow-step-start`**: A step begins execution
-- **`workflow-step-output`**: Custom output from a step
-- **`workflow-step-result`**: A step completes with results
-- **`workflow-finish`**: Workflow execution completes with usage statistics
-
-## Related
-
-- [Workflows overview](https://mastra.ai/docs/workflows/overview#running-workflows)
-- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
-- [Run.stream()](./stream)
-- [Run.resumeStream()](./resumeStream)
-
----
-
-## Reference: Run.resumeStream()
-
-> Documentation for the `Run.resumeStream()` method in workflows, which enables real-time resumption and streaming of suspended workflow runs.
-
-The `.resumeStream()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step and to observe the stream of events.
-
-## Usage example
-
-```typescript
-const run = await workflow.createRun();
-
-const stream = run.stream({
-  inputData: {
-    value: "initial data",
-  },
-});
-
-const result = await stream.result;
-
-if (result!.status === "suspended") {
-  const resumedStream = await run.resumeStream({
-    resumeData: {
-      value: "resume data",
-    },
-  });
-}
-```
-
-## Parameters
-
-## Returns
-
-## Stream Events
-
-The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
-
-- **`workflow-start`**: Workflow execution begins
-- **`workflow-step-start`**: A step begins execution
-- **`workflow-step-output`**: Custom output from a step
-- **`workflow-step-result`**: A step completes with results
-- **`workflow-finish`**: Workflow execution completes with usage statistics
-
-## Related
-
-- [Workflows overview](https://mastra.ai/docs/workflows/overview#running-workflows)
-- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
-- [Run.stream()](./stream)
-
----
-
-## Reference: Run.stream()
-
-> Documentation for the `Run.stream()` method in workflows, which enables real-time streaming of responses.
-
-The `.stream()` method enables real-time streaming of responses from a workflow. It returns a `ReadableStream` of events directly.
-
-## Usage example
-
-```typescript
-const run = await workflow.createRun();
-
-const stream = await run.stream({
-  inputData: {
-    value: "initial data",
-  },
-});
-
-for await (const chunk of stream) {
-  console.log(chunk);
-}
-```
-
-## Parameters
-
-## Returns
-
-Returns a `WorkflowRunOutput` object that implements the async iterable interface (can be used directly in `for await...of` loops) and provides access to the stream and workflow execution results.
-
-## Extended usage example
-
-```typescript
-const run = await workflow.createRun();
-
-const stream = run.stream({
-  inputData: {
-    value: "initial data",
-  },
-});
-
-// Iterate over stream events (you can iterate over stream directly or use stream.fullStream)
-for await (const chunk of stream) {
-  console.log(chunk);
-}
-
-// Access the final result
-const result = await stream.result;
-console.log("Final result:", result);
-
-// Access token usage
-const usage = await stream.usage;
-console.log("Token usage:", usage);
-
-// Check current status
-console.log("Status:", stream.status);
-```
-
-## Stream Events
-
-The stream emits various event types during workflow execution. Each event has a `type` field and a `payload` containing relevant data:
-
-- **`workflow-start`**: Workflow execution begins
-- **`workflow-step-start`**: A step begins execution
-- **`workflow-step-output`**: Custom output from a step
-- **`workflow-step-result`**: A step completes with results
-- **`workflow-finish`**: Workflow execution completes with usage statistics
-
-## Related
-
-- [Workflows overview](https://mastra.ai/docs/workflows/overview#running-workflows)
-- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
-- [Run.resumeStream()](./resumeStream)
-
----
-
-## Reference: Agent.streamLegacy() (Legacy)
-
-> Documentation for the legacy `Agent.streamLegacy()` method in Mastra agents. This method is deprecated and will be removed in a future version.
-
-> **Note:**
-
-**Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.stream()`](./stream) method instead. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for details on upgrading.
-
-The `.streamLegacy()` method is the legacy version of the agent streaming API, used for real-time streaming of responses from V1 model agents. This method accepts messages and optional streaming options.
-
-## Usage example
-
-```typescript
-await agent.streamLegacy("message for agent");
-```
-
-## Parameters
-
-### Options parameters
-
-## Returns
-
-## Extended usage example
-
-```typescript
-await agent.streamLegacy("message for agent", {
-  temperature: 0.7,
-  maxSteps: 3,
-  memory: {
-    thread: "user-123",
-    resource: "test-app",
-  },
-  toolChoice: "auto",
-});
-```
-
-## Migration to New API
-
-> **Note:**
-
-The new `.stream()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured output handling, and improved callback system. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for detailed migration instructions.
-
-### Quick Migration Example
-
-#### Before (Legacy)
-
-```typescript
-const result = await agent.streamLegacy("message", {
-  temperature: 0.7,
-  maxSteps: 3,
-  onFinish: (result) => console.log(result),
-});
-```
-
-#### After (New API)
-
-```typescript
-const result = await agent.stream("message", {
-  modelSettings: {
-    temperature: 0.7,
-  },
-  maxSteps: 3,
-  onFinish: (result) => console.log(result),
-});
-```
-
-## Related
-
-- [Migration Guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis)
-- [New .stream() method](./stream)
-- [Generating responses](https://mastra.ai/docs/agents/overview#generating-responses)
-- [Streaming responses](https://mastra.ai/docs/agents/overview#generating-responses)
-
----
-
-## Reference: Run.timeTravelStream()
-
-> Documentation for the `Run.timeTravelStream()` method for streaming workflow time travel execution.
-
-The `.timeTravelStream()` method re-executes a workflow starting from any specific step with streaming events. This allows you to receive real-time updates during time travel execution while maintaining full visibility into each step's progress.
-
-## Usage example
-
-```typescript
-const run = await workflow.createRun();
-
-const output = run.timeTravelStream({
-  step: "step2",
-  inputData: { value: 10 },
-});
-
-// Process events as they arrive
-for await (const event of output.fullStream) {
-  console.log(event.type, event.payload);
-}
-
-// Get the final result
-const result = await output.result;
-```
-
-## Parameters
-
-All parameters are the same as [`Run.timeTravel()`](../../workflows/run-methods/timeTravel#parameters). See the [timeTravel reference](../../workflows/run-methods/timeTravel#parameters) for detailed parameter documentation.
-
-## Returns
-
-## Stream events
-
-The stream emits various workflow events during execution:
-
-- `workflow-step-start`: Emitted when a step begins execution
-- `workflow-step-finish`: Emitted when a step completes successfully
-- `workflow-step-error`: Emitted when a step encounters an error
-- `workflow-step-suspended`: Emitted when a step suspends
-- Additional events depending on step types (agents, tools, etc.)
-
-## Extended usage examples
-
-### Processing events during time travel
-
-```typescript
-const run = await workflow.createRun();
-
-const output = run.timeTravelStream({
-  step: "step2",
-  inputData: { value: 10 },
-});
-
-for await (const event of output.fullStream) {
-  switch (event.type) {
-    case "workflow-step-start":
-      console.log(`Starting step: ${event.payload.stepName}`);
-      break;
-    case "workflow-step-finish":
-      console.log(`Completed step: ${event.payload.stepName}`);
-      break;
-    case "workflow-step-error":
-      console.error(`Error in step: ${event.payload.stepName}`, event.payload.error);
-      break;
-  }
-}
-
-const result = await output.result;
-console.log("Time travel completed:", result);
-```
-
-### Time travel stream with context
-
-```typescript
-const output = run.timeTravelStream({
-  step: "step2",
-  context: {
-    step1: {
-      status: "success",
-      payload: { value: 0 },
-      output: { step1Result: 2 },
-      startedAt: Date.now(),
-      endedAt: Date.now(),
-    },
-  },
-});
-
-for await (const event of output.fullStream) {
-  // Handle events
-  console.log(event);
-}
-
-const result = await output.result;
-```
-
-### Time travel stream with nested workflows
-
-```typescript
-const output = run.timeTravelStream({
-  step: ["nestedWorkflow", "step3"],
-  inputData: { value: 10 },
-  nestedStepsContext: {
-    nestedWorkflow: {
-      step2: {
-        status: "success",
-        payload: { step1Result: 2 },
-        output: { step2Result: 3 },
-        startedAt: Date.now(),
-        endedAt: Date.now(),
-      },
-    },
-  },
-});
-
-for await (const event of output.fullStream) {
-  console.log(event.type, event.payload);
-}
-
-const result = await output.result;
-```
-
-## Notes
-
-- The stream closes automatically when time travel execution completes or encounters an error
-- You can process events from the stream while the workflow is still executing
-- The `result` promise resolves only after all steps have completed
-- Stream events follow the same format as regular workflow streaming
-- Time travel streaming requires storage to be configured since it relies on persisted workflow snapshots
-
-## Related
-
-- [Run.timeTravel()](../../workflows/run-methods/timeTravel)
-- [Time Travel](https://mastra.ai/docs/workflows/time-travel)
-- [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming)
-- [Run.stream()](./stream)
-- [Run.resumeStream()](./resumeStream)