@mastra/mcp-docs-server 0.13.27 → 0.13.28-alpha.2

package/.docs/raw/agents/guardrails.mdx

@@ -0,0 +1,335 @@
+---
+title: "Guardrails | Agents | Mastra Docs"
+description: "Learn how to implement guardrails using input and output processors to secure and control AI interactions."
+---
+
+# Guardrails
+
+Agents use processors to apply guardrails to inputs and outputs. They run before or after each interaction, giving you a way to review, transform, or block information as it passes between the user and the agent.
+
+Processors can be configured as:
+
+- **`inputProcessors`**: Applied before messages reach the language model.
+- **`outputProcessors`**: Applied to responses before they're returned to users.
+
+Some processors are *hybrid*, meaning they can be used with either `inputProcessors` or `outputProcessors`, depending on where the logic should be applied.
+
+## When to use processors
+
+Use processors for content moderation, prompt injection prevention, response sanitization, message transformation, and other security-related controls. Mastra provides several built-in input and output processors for common use cases.
+
+## Adding processors to an agent
+
+Import and instantiate the relevant processor class, and pass it to your agent’s configuration using either the `inputProcessors` or `outputProcessors` parameter:
+
+```typescript {3,9-17} filename="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { ModerationProcessor } from "@mastra/core/processors";
+
+export const moderatedAgent = new Agent({
+  name: "moderated-agent",
+  instructions: "You are a helpful assistant",
+  model: openai("gpt-4o-mini"),
+  inputProcessors: [
+    new ModerationProcessor({
+      model: openai("gpt-4.1-nano"),
+      categories: ["hate", "harassment", "violence"],
+      threshold: 0.7,
+      strategy: "block",
+      instructions: "Detect and flag inappropriate content in user messages",
+    })
+  ]
+});
+```
+
+## Input processors
+
+Input processors are applied before user messages reach the language model. They are useful for normalization, validation, content moderation, prompt injection detection, and security checks.
+
+### Normalizing user messages
+
+The `UnicodeNormalizer` is an input processor that cleans and normalizes user input by unifying Unicode characters, standardizing whitespace, and removing problematic symbols, allowing the LLM to better understand user messages.
+
+```typescript {6-9} filename="src/mastra/agents/normalized-agent.ts" showLineNumbers copy
+import { UnicodeNormalizer } from "@mastra/core/processors";
+
+export const normalizedAgent = new Agent({
+  // ...
+  inputProcessors: [
+    new UnicodeNormalizer({
+      stripControlChars: true,
+      collapseWhitespace: true,
+    })
+  ],
+});
+```
+
+> See [UnicodeNormalizer](../../reference/processors/unicode-normalizer.mdx) for a full list of configuration options.
+
+### Preventing prompt injection
+
+The `PromptInjectionDetector` is an input processor that scans user messages for prompt injection, jailbreak attempts, and system override patterns. It uses an LLM to classify risky input and can block or rewrite it before it reaches the model.
+
+```typescript {6-11} filename="src/mastra/agents/secure-agent.ts" showLineNumbers copy
+import { PromptInjectionDetector } from "@mastra/core/processors";
+
+export const secureAgent = new Agent({
+  // ...
+  inputProcessors: [
+    new PromptInjectionDetector({
+      model: openai("gpt-4.1-nano"),
+      threshold: 0.8,
+      strategy: 'rewrite',
+      detectionTypes: ['injection', 'jailbreak', 'system-override'],
+    })
+  ],
+});
+```
+
+> See [PromptInjectionDetector](../../reference/processors/prompt-injection-detector.mdx) for a full list of configuration options.
+
+### Detecting and translating language
+
+The `LanguageDetector` is an input processor that detects and translates user messages into a target language, enabling multilingual support while maintaining consistent interaction. It uses an LLM to identify the language and perform the translation.
+
+```typescript {6-11} filename="src/mastra/agents/multilingual-agent.ts" showLineNumbers copy
+import { LanguageDetector } from "@mastra/core/processors";
+
+export const multilingualAgent = new Agent({
+  // ...
+  inputProcessors: [
+    new LanguageDetector({
+      model: openai("gpt-4.1-nano"),
+      targetLanguages: ['English', 'en'],
+      strategy: 'translate',
+      threshold: 0.8,
+    })
+  ],
+});
+```
+
+> See [LanguageDetector](../../reference/processors/language-detector.mdx) for a full list of configuration options.
+
+## Output processors
+
+Output processors are applied after the language model generates a response, but before it is returned to the user. They are useful for response optimization, moderation, transformation, and applying safety controls.
+
+### Batching streamed output
+
+The `BatchPartsProcessor` is an output processor that combines multiple stream parts before emitting them to the client. This reduces network overhead and improves the user experience by consolidating small chunks into larger batches.
+
+```typescript {6-10} filename="src/mastra/agents/batched-agent.ts" showLineNumbers copy
+import { BatchPartsProcessor } from "@mastra/core/processors";
+
+export const batchedAgent = new Agent({
+  // ...
+  outputProcessors: [
+    new BatchPartsProcessor({
+      batchSize: 5,
+      maxWaitTime: 100,
+      emitOnNonText: true
+    })
+  ]
+});
+```
+
+> See [BatchPartsProcessor](../../reference/processors/batch-parts-processor.mdx) for a full list of configuration options.
+
+### Limiting token usage
+
+The `TokenLimiterProcessor` is an output processor that limits the number of tokens in model responses. It helps manage cost and performance by truncating or blocking messages when the limit is exceeded.
+
+```typescript {6-10, 13-15} filename="src/mastra/agents/limited-agent.ts" showLineNumbers copy
+import { TokenLimiterProcessor } from "@mastra/core/processors";
+
+export const limitedAgent = new Agent({
+  // ...
+  outputProcessors: [
+    new TokenLimiterProcessor({
+      limit: 1000,
+      strategy: "truncate",
+      countMode: "cumulative"
+    })
+  ]
+})
+```
+
+> See [TokenLimiterProcessor](../../reference/processors/token-limiter-processor.mdx) for a full list of configuration options.
+
+### Scrubbing system prompts
+
+The `SystemPromptScrubber` is an output processor that detects and redacts system prompts or other internal instructions from model responses. It helps prevent unintended disclosure of prompt content or configuration details that could introduce security risks. It uses an LLM to identify and redact sensitive content based on configured detection types.
+
+```typescript {5-13} filename="src/mastra/agents/scrubbed-agent.ts" copy showLineNumbers
+import { SystemPromptScrubber } from "@mastra/core/processors";
+
+const scrubbedAgent = new Agent({
+  outputProcessors: [
+    new SystemPromptScrubber({
+      model: openai("gpt-4.1-nano"),
+      strategy: "redact",
+      customPatterns: ["system prompt", "internal instructions"],
+      includeDetections: true,
+      instructions: "Detect and redact system prompts, internal instructions, and security-sensitive content",
+      redactionMethod: "placeholder",
+      placeholderText: "[REDACTED]"
+    })
+  ]
+});
+```
+
+> See [SystemPromptScrubber](../../reference/processors/system-prompt-scrubber.mdx) for a full list of configuration options.
+
+## Hybrid processors
+
+Hybrid processors can be applied either before messages are sent to the language model or before responses are returned to the user. They are useful for tasks like content moderation and PII redaction.
+
+### Moderating input and output
+
+The `ModerationProcessor` is a hybrid processor that detects inappropriate or harmful content across categories like hate, harassment, and violence. It can be used to moderate either user input or model output, depending on where it's applied. It uses an LLM to classify the message and can block or rewrite it based on your configuration.
+
+```typescript {6-11, 14-16} filename="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
+import { ModerationProcessor } from "@mastra/core/processors";
+
+export const moderatedAgent = new Agent({
+  // ...
+  inputProcessors: [
+    new ModerationProcessor({
+      model: openai("gpt-4.1-nano"),
+      threshold: 0.7,
+      strategy: "block",
+      categories: ["hate", "harassment", "violence"]
+    })
+  ],
+  outputProcessors: [
+    new ModerationProcessor({
+      // ...
+    })
+  ]
+});
+```
+
+> See [ModerationProcessor](../../reference/processors/moderation-processor.mdx) for a full list of configuration options.
+
+### Detecting and redacting PII
+
+The `PIIDetector` is a hybrid processor that detects and removes personally identifiable information such as emails, phone numbers, and credit cards. It can redact either user input or model output, depending on where it's applied. It uses an LLM to identify sensitive content based on configured detection types.
+
+```typescript {6-13, 16-18} filename="src/mastra/agents/private-agent.ts" showLineNumbers copy
+import { PIIDetector } from "@mastra/core/processors";
+
+export const privateAgent = new Agent({
+  // ...
+  inputProcessors: [
+    new PIIDetector({
+      model: openai("gpt-4.1-nano"),
+      threshold: 0.6,
+      strategy: 'redact',
+      redactionMethod: 'mask',
+      detectionTypes: ['email', 'phone', 'credit-card'],
+      instructions: "Detect and mask personally identifiable information."
+    })
+  ],
+  outputProcessors: [
+    new PIIDetector({
+      // ...
+    })
+  ]
+});
+```
+
+> See [PIIDetector](../../reference/processors/pii-detector.mdx) for a full list of configuration options.
+
+## Applying multiple processors
+
+You can apply multiple processors by listing them in the `inputProcessors` or `outputProcessors` array. They run in sequence, with each processor receiving the output of the one before it.
+
+A typical order might be:
+
+1. **Normalization**: Standardize input format (`UnicodeNormalizer`).
+2. **Security checks**: Detect threats or sensitive content (`PromptInjectionDetector`, `PIIDetector`).
+3. **Filtering**: Block or transform messages (`ModerationProcessor`).
+
+The order affects behavior, so arrange processors to suit your goals.
+
+```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
+import {
+  UnicodeNormalizer,
+  ModerationProcessor,
+  PromptInjectionDetector,
+  PIIDetector
+  } from "@mastra/core/processors";
+
+export const testAgent = new Agent({
+  // ...
+  inputProcessors: [
+    new UnicodeNormalizer({
+      //...
+    }),
+    new PromptInjectionDetector({
+      // ...
+    }),
+    new PIIDetector({
+      // ...
+    }),
+    new ModerationProcessor({
+      // ...
+    })
+  ],
+});
+```
+
+## Processor strategies
+
+Many of the built-in processors support a `strategy` parameter that controls how they handle flagged input or output. Supported values may include: `block`, `warn`, `detect`, or `redact`.
+
+Most strategies allow the request to continue without interruption. When `block` is used, the processor calls its internal `abort()` function, which immediately stops the request and prevents any subsequent processors from running.
+
+```typescript {8} filename="src/mastra/agents/private-agent.ts" showLineNumbers copy
+import { PIIDetector } from "@mastra/core/processors";
+
+export const privateAgent = new Agent({
+  // ...
+  inputProcessors: [
+    new PIIDetector({
+      // ...
+      strategy: "block"
+    })
+  ]
+})
+```
+
+### Handling blocked requests
+
+When a processor blocks a request, the agent will still return successfully without throwing an error. To handle blocked requests, check for `tripwire` or `tripwireReason` in the response.
+
+For example, if an agent uses the `PIIDetector` with `strategy: "block"` and the request includes a credit card number, it will be blocked and the response will include a `tripwireReason`.
+
+#### `.generate()` example
+
+```typescript {3-4, } showLineNumbers
+const result = await agent.generate("Is this credit card number valid?: 4543 1374 5089 4332");
+
+console.error(result.tripwire);
+console.error(result.tripwireReason);
+```
+#### `.stream()` example
+
+```typescript {4-5} showLineNumbers
+const stream = await agent.stream("Is this credit card number valid?: 4543 1374 5089 4332");
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "tripwire") {
+    console.error(chunk.payload.tripwireReason);
+  }
+}
+```
+
+In this case, the `tripwireReason` indicates that a credit card number was detected:
+
+```text
+PII detected. Types: credit-card
+```
+
+

package/.docs/raw/{networks-vnext/complex-task-execution.mdx → agents/networks.mdx}

@@ -1,27 +1,47 @@
 ---
-title: "Complex Task Execution with AgentNetwork Loop Method"
-description: "This page demonstrates how to use the AgentNetwork's loop method in Mastra vNext to handle complex tasks that require multiple agents and workflows, including memory-based orchestration and multi-step execution."
+title: "Handling Complex LLM Operations | Networks | Mastra"
+description: "Networks in Mastra help you execute individual or multiple Mastra primitives in a non-deterministic way using a single API."
 ---
 
-## Complex tasks requiring multiple primitives
+# Agent.network()
 
-As an example, we have an AgentNetwork with 3 primitives at its disposal:
+`Agent.network()` introduces a flexible, composable and non-deterministic way to orchestrate multiple specialized agents and workflows, enabling complex, reasoning and task completion.
+
+There are two main problem areas that this system is designed to solve:
+
+- Scenarios where a single agent is insufficient, and tasks require collaboration, routing, or sequential/parallel execution across multiple agents and workflows.
+- Scenarios where the task is not fully defined and is initiated with unstructured input. A network allows your Agent to figure out which primitive to call and turn unstructured input into a structured task.
+
+## Differences from Workflows
+
+- Workflows are linear or branched sequences of steps. This creates a deterministic flow of execution.
+- `Agent.network()` adds a layer of non-deterministic LLM-based orchestration, allowing dynamic, multi-agent collaboration and routing. This creates a non-deterministic flow of execution.
+
+## Important details
+
+- Providing memory to the Agent when using `network()` is _not_ optional, as it is required to store the task history. Memory is the core primitive used for any decisions on which primitives to run, as well as determine task completion.
+- Any available primitives (agents, workflows) are used based on their descriptions. The better the description, the better the routing agent will be able to select the right primitive. For workflows, the input schema is also used to determine which inputs to use when calling the workflow. More descriptive naming yields better results.
+- When primitives with overlapping capabilities are available, the agent will use the most specific primitive. For example, if both an agent and a workflow can do research, it will use the input schema of the workflow to determine which primitive to select.
+
+## Turning an Agent into a Network
+
+As an example, we have an Agent with 3 primitives at its disposal:
 
 - `agent1`: A general research agent that can do research on a given topic.
 - `agent2`: A general writing agent that can write a full report based on the researched material.
 - `workflow1`: A workflow that can research a given city and write a full report based on the researched material (using both agent1 and agent2).
 
-We use the `loop` method to create a task that requires multiple primitives. The AgentNetwork will, using memory, figure out which primitives to call and in which order, as well as when the task is complete.
+We use the `network` method to create a task that requires multiple primitives. The Agent will, using memory, figure out which primitives to call and in which order, as well as when the task is complete.
+
 
 ```typescript
-import { NewAgentNetwork } from '@mastra/core/network/vNext';
 import { Agent } from '@mastra/core/agent';
 import { createStep, createWorkflow } from '@mastra/core/workflows';
+import { RuntimeContext } from '@mastra/core/runtime-context';
 import { Memory } from '@mastra/memory';
 import { openai } from '@ai-sdk/openai';
 import { LibSQLStore } from '@mastra/libsql';
 import { z } from 'zod';
-import { RuntimeContext } from '@mastra/core/runtime-context';
 
 const memory = new Memory({
   storage: new LibSQLStore({
@@ -103,7 +123,7 @@ const agent2 = new Agent({
   model: openai('gpt-4o'),
 });
 
-const network = new NewAgentNetwork({
+const routingAgent = new Agent({
   id: 'test-network',
   name: 'Test Network',
   instructions:
@@ -123,7 +143,7 @@ const runtimeContext = new RuntimeContext();
 
 console.log(
   // specifying the task, note that there is a mention here about using an agent for synthesis. This is because the routing agent can actually do some synthesis on results on its own, so this will force it to use agent2 instead
-  await network.loop(
+  await routingAgent.network(
     'What are the biggest cities in France? Give me 3. How are they like? Find cities, then do thorough research on each city, and give me a final full report synthesizing all that information. Make sure to use an agent for synthesis.',
     { runtimeContext },
   ),

package/.docs/raw/agents/overview.mdx

@@ -3,55 +3,77 @@ title: "Agent Overview | Agents | Mastra Docs"
 description: Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
 ---
 
-import { Steps } from "nextra/components";
+import { Steps, Callout, Tabs } from "nextra/components";
 
 # Using Agents
 
-Agents let you build intelligent assistants powered by language models that can make decisions and perform actions. Each agent has required instructions and an LLM, with optional tools and memory.
-
-An agent coordinates conversations, calls tools when needed, maintains context through memory, and produces responses tailored to the interaction. Agents can operate on their own or work as part of larger workflows.
+Agents use LLMs and tools to solve open-ended tasks. They reason about goals, decide which tools to use, retain conversation memory, and iterate internally until the model emits a final answer or an optional stop condition is met. Agents produce structured responses you can render in your UI or process programmatically. Use agents directly or compose them into workflows or agent networks.
 
 ![Agents overview](/image/agents/agents-overview.jpg)
 
-To create an agent:
-
-- Define **instructions** with the `Agent` class and set the **LLM** it will use.
-- Optionally configure **tools** and **memory** to extend functionality.
-- Run the agent to generate responses, with support for streaming, structured output, and dynamic configuration.
-
-This approach provides type safety and runtime validation, ensuring reliable behavior across all agent interactions.
-
 > **📹 Watch**:  → An introduction to agents, and how they compare to workflows [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
 
 ## Getting started
 
-To use agents, install the required dependencies:
+<Tabs items={["Mastra model router", "Vercel AI SDK"]}>
+  <Tabs.Tab>
+    <Steps>
+### Install dependencies
+
+Add the Mastra core package to your project:
 
 ```bash
-npm install @mastra/core @ai-sdk/openai
+npm install @mastra/core
 ```
 
-> Mastra works with all AI SDK provider. See [Model Providers](../getting-started/model-providers.mdx) for more information.
+### Set your API key
+
+Mastra's model router auto-detects environment variables for your chosen provider. For OpenAI, set `OPENAI_API_KEY`:
 
-Import the necessary class from the agents module, and an LLM provider:
+```bash filename=".env" copy
+OPENAI_API_KEY=<your-api-key>
+```
+
+> Mastra supports more than 600 models. Choose from the full list [here](../getting-started/model-providers.mdx).
+
+### Create an agent
+
+Create an agent by instantiating the `Agent` class with system `instructions` and a `model`:
 
 ```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
+
+export const testAgent = new Agent({
+  name: "test-agent",
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-4o-mini"
+});
 ```
-### LLM providers
+    </Steps>
+  </Tabs.Tab>
+  <Tabs.Tab>
+    <Steps>
+### Install dependencies
 
-Each LLM provider needs its own API key, named using the provider’s identifier:
+Include the Mastra core package alongside the Vercel AI SDK provider you want to use:
+
+```bash
+npm install @mastra/core @ai-sdk/openai
+```
+
+### Set your API key
+
+Set the corresponding environment variable for your provider. For OpenAI via the AI SDK:
 
 ```bash filename=".env" copy
 OPENAI_API_KEY=<your-api-key>
 ```
 
-> See the [AI SDK Providers](https://ai-sdk.dev/providers/ai-sdk-providers) in the Vercel AI SDK docs.
+> See the [AI SDK Providers](https://ai-sdk.dev/providers/ai-sdk-providers) in the Vercel AI SDK docs for additional configuration options.
 
-### Creating an agent
+### Create an agent
 
-To create an agent in Mastra, use the `Agent` class. Every agent must include `instructions` to define its behavior, and a `model` parameter to specify the LLM provider and model:
+To create an agent in Mastra, use the `Agent` class. Every agent must include `instructions` to define its behavior, and a `model` parameter to specify the LLM provider and model. When using the Vercel AI SDK, provide the client to your agent's `model` field:
 
 ```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
 import { openai } from "@ai-sdk/openai";
@@ -63,24 +85,21 @@ export const testAgent = new Agent({
   model: openai("gpt-4o-mini")
 });
 ```
+    </Steps>
+  </Tabs.Tab>
+</Tabs>
 
 #### Instruction formats
 
 Instructions define the agent's behavior, personality, and capabilities.
 They are system-level prompts that establish the agent's core identity and expertise.
 
-Instructions can be provided in multiple formats for greater flexibility:
+Instructions can be provided in multiple formats for greater flexibility. The examples below illustrate the supported shapes:
 
-```typescript showLineNumbers copy
+```typescript copy
 // String (most common)
 instructions: "You are a helpful assistant."
 
-// System message object
-instructions: {
-  role: "system",
-  content: "You are an expert programmer."
-}
-
 // Array of strings
 instructions: [
   "You are a helpful assistant.",
@@ -93,11 +112,18 @@ instructions: [
   { role: "system", content: "You are a helpful assistant." },
   { role: "system", content: "You have expertise in TypeScript." }
 ]
+```
+
+#### Provider-specific options
 
+Each model provider also enables a few different options, including prompt caching and configuring reasoning. We provide a `providerOptions` flag to manage these. You can set `providerOptions` on the instruction level to set different caching strategy per system instruction/prompt.
+
+```typescript copy
 // With provider-specific options (e.g., caching, reasoning)
 instructions: {
   role: "system",
-  content: "You are an expert code reviewer. Analyze code for bugs, performance issues, and best practices.",
+  content:
+    "You are an expert code reviewer. Analyze code for bugs, performance issues, and best practices.",
   providerOptions: {
     openai: { reasoning_effort: "high" },        // OpenAI's reasoning models
     anthropic: { cache_control: { type: "ephemeral" } }  // Anthropic's prompt caching
@@ -105,12 +131,7 @@ instructions: {
 }
 ```
 
-Provider-specific options allow you to leverage unique features of different LLM providers:
-- **Anthropic caching**: Reduce costs by caching frequently-used instructions
-- **OpenAI reasoning**: Enable deeper analysis for complex tasks
-- **Custom parameters**: Pass any provider-specific configuration
-
-> See [Agent](../../reference/agents/agent.mdx) for more information.
+> See the [Agent reference doc](../../reference/agents/agent.mdx) for more information.
 
 ### Registering an agent
 
@@ -133,18 +154,23 @@ You can call agents from workflow steps, tools, the Mastra Client, or the comman
 ```typescript showLineNumbers copy
 const testAgent = mastra.getAgent("testAgent");
 ```
+<Callout type="info">
+  <p>
+    `mastra.getAgent()` is preferred over a direct import, since it preserves the Mastra instance configuration (tools registered, telemetry, vector stores configuration for agent memory, etc.)
+  </p>
+</Callout>
 
 > See [Calling agents](../../examples/agents/calling-agents.mdx) for more information.
 
 ## Generating responses
 
-Use `.generate()` to get a response from an agent. Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content` for precise control over roles and conversational flows.
+Agents can return results in two ways: generating the full output before returning it or streaming tokens in real time. Choose the approach that fits your use case: generate for short, internal responses or debugging, and stream to deliver pixels to end users as quickly as possible.
 
-> See [.generate()](../../reference/agents/generate.mdx) for more information.
+<Tabs items={["Generate", "Stream"]}>
+  <Tabs.Tab>
+Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content`.
 
-### Generating text
-
-Call `.generate()` with an array of message objects containing `role` and `content`. The `role` defines the speaker for each message. Typical roles are `user` for human input, `assistant` for agent responses, and `system` for instructions. This structure helps the LLM maintain conversation flow and generate contextually appropriate responses.
+(The `role` defines the speaker for each message. Typical roles are `user` for human input, `assistant` for agent responses, and `system` for instructions.)
 
 ```typescript showLineNumbers copy
 const response = await testAgent.generate([
@@ -156,6 +182,45 @@ const response = await testAgent.generate([
 
 console.log(response.text);
 ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+Pass a single string for simple prompts, an array of strings when providing multiple pieces of context, or an array of message objects with `role` and `content`.
+
+(The `role` defines the speaker for each message. Typical roles are `user` for human input, `assistant` for agent responses, and `system` for instructions.)
+
+```typescript showLineNumbers copy
+const stream = await testAgent.stream([
+  { role: "user", content: "Help me organize my day" },
+  { role: "user", content: "My day starts at 9am and finishes at 5.30pm" },
+  { role: "user", content: "I take lunch between 12:30 and 13:30" },
+  { role: "user", content: "I have meetings Monday to Friday between 10:30 and 11:30" }
+]);
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Completion using `onFinish()`
+
+When streaming responses, the `onFinish()` callback runs after the LLM finishes generating its response and all tool executions are complete.
+It provides the final `text`, execution `steps`, `finishReason`, token `usage` statistics, and other metadata useful for monitoring or logging.
+
+```typescript showLineNumbers copy
+const stream = await testAgent.stream("Help me organize my day", {
+  onFinish: ({ steps, text, finishReason, usage }) => {
+    console.log({ steps, text, finishReason, usage });
+  }
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+  </Tabs.Tab>
+</Tabs>
+
+> See [.generate()](../../reference/agents/generate.mdx) or [.stream()](../../reference/agents/stream.mdx) for more information.
 
 ## Structured output
 
@@ -189,27 +254,6 @@ const response = await testAgent.generate(
 
 console.log(response.object);
 ```
-
-#### Agents with tools
-
-To generate structured output with agents that use tools, use the `output` property:
-
-```typescript {6} showLineNumbers copy
-import { z } from "zod";
-
-const response = await testAgent.generate(
-  // ...
-  {
-    output: z.object({
-      summary: z.string(),
-      keywords: z.array(z.string())
-    })
-  }
-);
-
-console.log(response.object);
-```
-
 ## Working with images
 
 Agents can analyze and describe images by processing both the visual content and any text within them. To enable image analysis, pass an object with `type: 'image'` and the image URL in the `content` array. You can combine image content with text prompts to guide the agent's analysis.