@mastra/core 1.15.0-alpha.0 → 1.15.0-alpha.2

package/dist/docs/references/docs-memory-overview.md

@@ -2,44 +2,239 @@
 
 Memory enables your agent to remember user messages, agent replies, and tool results across interactions, giving it the context it needs to stay consistent, maintain conversation flow, and produce better answers over time.
 
-Mastra supports four complementary memory types:
+Mastra agents can be configured to store [message history](https://mastra.ai/docs/memory/message-history). Additionally, you can enable:
 
-- [**Message history**](https://mastra.ai/docs/memory/message-history) - keeps recent messages from the current conversation so they can be rendered in the UI and used to maintain short-term continuity within the exchange.
-- [**Observational memory**](https://mastra.ai/docs/memory/observational-memory) - uses background Observer and Reflector agents to maintain a dense observation log that replaces raw message history as it grows, keeping the context window small while preserving long-term memory across conversations.
-- [**Working memory**](https://mastra.ai/docs/memory/working-memory) - stores persistent, structured user data such as names, preferences, and goals.
-- [**Semantic recall**](https://mastra.ai/docs/memory/semantic-recall) - retrieves relevant messages from older conversations based on semantic meaning rather than exact keywords, mirroring how humans recall information by association. Requires a [vector database](https://mastra.ai/docs/memory/semantic-recall) and an [embedding model](https://mastra.ai/docs/memory/semantic-recall).
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory) (Recommended): Uses background agents to maintain a dense observation log that replaces raw message history as it grows. This keeps the context window small while preserving long-term memory.
+- [Working memory](https://mastra.ai/docs/memory/working-memory): Stores persistent, structured user data such as names, preferences, and goals.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): Retrieves relevant past messages based on semantic meaning rather than exact keywords.
 
 If the combined memory exceeds the model's context limit, [memory processors](https://mastra.ai/docs/memory/memory-processors) can filter, trim, or prioritize content so the most relevant information is preserved.
 
-## Getting started
+Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/memory/storage).
 
-Choose a memory option to get started:
+## When to use memory
 
-- [Message history](https://mastra.ai/docs/memory/message-history)
-- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
-- [Working memory](https://mastra.ai/docs/memory/working-memory)
-- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall)
+Use memory when your agent needs to maintain multi-turn conversations that reference prior exchanges, recall user preferences or facts from earlier in a session, or build context over time within a conversation thread. Skip memory for single-turn requests where each interaction is independent.
 
-## Storage
+## Quickstart
 
-Before enabling memory, you must first configure a storage adapter. Mastra supports several databases including PostgreSQL, MongoDB, libSQL, and [more](https://mastra.ai/docs/memory/storage).
+1. Install the `@mastra/memory` package.
 
-Storage can be configured at the [instance level](https://mastra.ai/docs/memory/storage) (shared across all agents) or at the [agent level](https://mastra.ai/docs/memory/storage) (dedicated per agent).
+   **npm**:
 
-For semantic recall, you can use a separate vector database like Pinecone alongside your primary storage.
+   ```bash
+   npm install @mastra/memory@latest
+   ```
 
-See the [Storage](https://mastra.ai/docs/memory/storage) documentation for configuration options, supported providers, and examples.
+   **pnpm**:
 
-## Debugging memory
+   ```bash
+   pnpm add @mastra/memory@latest
+   ```
 
-When [tracing](https://mastra.ai/docs/observability/tracing/overview) is enabled, you can inspect exactly which messages the agent uses for context in each request. The trace output shows all memory included in the agent's context window - both recent message history and messages recalled via semantic recall.
+   **Yarn**:
 
-![Trace output showing memory context included in an agent request](https://mastra.ai/_next/image?url=%2Ftracingafter.png\&w=1920\&q=75)
+   ```bash
+   yarn add @mastra/memory@latest
+   ```
 
-This visibility helps you understand why an agent made specific decisions and verify that memory retrieval is working as expected.
+   **Bun**:
 
-## Next steps
+   ```bash
+   bun add @mastra/memory@latest
+   ```
 
-- Learn more about [Storage](https://mastra.ai/docs/memory/storage) providers and configuration options
-- Add [Message history](https://mastra.ai/docs/memory/message-history), [Observational memory](https://mastra.ai/docs/memory/observational-memory), [Working memory](https://mastra.ai/docs/memory/working-memory), or [Semantic recall](https://mastra.ai/docs/memory/semantic-recall)
-- Visit [Memory configuration reference](https://mastra.ai/reference/memory/memory-class) for all available options
+2. Memory **requires** a storage provider to persist message history, including user messages and agent responses.
+
+   For the purposes of this quickstart, use `@mastra/libsql`.
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/libsql@latest
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/libsql@latest
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/libsql@latest
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/libsql@latest
+   ```
+
+   > **Note:** For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/memory/storage) documentation.
+
+3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
+
+   ```typescript
+   import { Mastra } from '@mastra/core'
+   import { LibSQLStore } from '@mastra/libsql'
+
+   export const mastra = new Mastra({
+     storage: new LibSQLStore({
+       id: 'mastra-storage',
+       url: ':memory:',
+     }),
+   })
+   ```
+
+4. Create a `Memory` instance and pass it to the agent's `memory` option.
+
+   ```typescript
+   import { Agent } from '@mastra/core/agent'
+   import { Memory } from '@mastra/memory'
+
+   export const memoryAgent = new Agent({
+     id: 'memory-agent',
+     name: 'Memory Agent',
+     memory: new Memory({
+       options: {
+         lastMessages: 20,
+       },
+     }),
+   })
+   ```
+
+   > **Note:** Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
+
+5. Call your agent, for example in [Mastra Studio](https://mastra.ai/docs/getting-started/studio). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
+
+## Message history
+
+Pass a `memory` object with `resource` and `thread` to track message history.
+
+- `resource`: A stable identifier for the user or entity.
+- `thread`: An ID that isolates a specific conversation or session.
+
+```typescript
+const response = await memoryAgent.generate('Remember my favorite color is blue.', {
+  memory: {
+    resource: 'user-123',
+    thread: 'conversation-123',
+  },
+})
+```
+
+To recall information stored in memory, call the agent with the same `resource` and `thread` values used in the original conversation.
+
+```typescript
+const response = await memoryAgent.generate("What's my favorite color?", {
+  memory: {
+    resource: 'user-123',
+    thread: 'conversation-123',
+  },
+})
+
+// Response: "Your favorite color is blue."
+```
+
+> **Warning:** Each thread has an owner (`resourceId`) that can't be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.
+
+To list all threads for a resource, or retrieve a specific thread, [use the memory API directly](https://mastra.ai/docs/memory/message-history).
+
+## Observational Memory
+
+For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  memory: new Memory({
+    options: {
+      observationalMemory: true,
+    },
+  }),
+})
+```
+
+> **Note:** See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
+
+## Memory in multi-agent systems
+
+When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. There is no flag to enable this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
+
+### How delegation scopes memory
+
+Each delegation creates a fresh `threadId` and a deterministic `resourceId` for the subagent:
+
+- **Thread ID**: Unique per delegation. The subagent starts with a clean message history every time it's called.
+- **Resource ID**: Derived as `{parentResourceId}-{agentName}`. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
+- **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance. If the subagent defines its own, that takes precedence.
+
+The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation is not stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
+
+> **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Two different subagents under the same supervisor never share a resource ID through delegation.
+
+To go beyond this default isolation, you can share memory between agents by passing matching identifiers when you call them directly.
+
+### Share memory between agents
+
+When you call agents directly (outside the delegation flow), memory sharing is controlled by two identifiers: `resourceId` and `threadId`. Agents that use the same values read and write to the same data. This is useful when agents collaborate on a shared context — for example, a researcher that saves notes and a writer that reads them.
+
+**Resource-scoped sharing** is the most common pattern. [Working memory](https://mastra.ai/docs/memory/working-memory) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) default to `scope: 'resource'`. If two agents share a `resourceId`, they share observations, working memory, and embeddings — even across different threads:
+
+```typescript
+// Both agents share the same resource-scoped memory
+await researcher.generate('Find information about quantum computing.', {
+  memory: { resource: 'project-42', thread: 'research-session' },
+})
+
+await writer.generate('Write a summary from the research notes.', {
+  memory: { resource: 'project-42', thread: 'writing-session' },
+})
+```
+
+Because both calls use `resource: 'project-42'`, the writer can access the researcher's observations, working memory, and semantic embeddings. Each agent still has its own thread, so message histories stay separate.
+
+**Thread-scoped sharing** gives tighter coupling. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses `scope: 'thread'` by default. If two agents use the same `resource` _and_ `thread`, they share the full message history. Each agent sees every message the other has written. This is useful when agents need to build on each other's exact outputs.
+
+## Observability
+
+Enable [Tracing](https://mastra.ai/docs/observability/tracing/overview) to monitor and debug memory in action. Traces show you exactly which messages and observations the agent included in its context for each request, helping you understand agent behavior and verify that memory retrieval is working as expected.
+
+Open [Mastra Studio](https://mastra.ai/docs/getting-started/studio) and select the **Observability** tab in the sidebar. Open the trace of a recent agent request, then look for spans of LLMs calls.
+
+## Switch memory per request
+
+Use [`RequestContext`](https://mastra.ai/docs/server/request-context) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
+
+```typescript
+export type UserTier = {
+  'user-tier': 'enterprise' | 'pro'
+}
+
+const premiumMemory = new Memory()
+const standardMemory = new Memory()
+
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  memory: ({ requestContext }) => {
+    const userTier = requestContext.get('user-tier') as UserTier['user-tier']
+
+    return userTier === 'enterprise' ? premiumMemory : standardMemory
+  },
+})
+```
+
+> **Note:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+
+## Related
+
+- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
+- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
+- [Request Context](https://mastra.ai/docs/server/request-context)

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -16,7 +16,7 @@ When it's enabled, new messages are used to query a vector DB for semantically s
 
 After getting a response from the LLM, all new messages (user, assistant, and tool calls/results) are inserted into the vector DB to be recalled in later interactions.
 
-## Quick start
+## Quickstart
 
 Semantic recall is enabled by default, so if you give your agent memory it will be included:
 

package/dist/docs/references/docs-memory-storage.md

@@ -100,7 +100,7 @@ This is useful when different types of data have different performance or operat
 
 ### Agent-level storage
 
-Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need data boundaries or compliance requirements:
+Agent-level storage overrides storage configured at the instance level. Add storage to a specific agent when you need to keep data separate or use different providers per agent.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -118,14 +118,14 @@ export const agent = new Agent({
 })
 ```
 
-> **Warning:** [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment) doesn't support agent-level storage.
+> **Warning:** Agent-level storage isn't supported when using [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation doesn't apply if you bring your own database.
 
 ## Threads and resources
 
 Mastra organizes conversations using two identifiers:
 
-- **Thread** - a conversation session containing a sequence of messages.
-- **Resource** - the entity that owns the thread, such as a user, organization, project, or any other domain entity in your application.
+- **Thread**: A conversation session containing a sequence of messages.
+- **Resource**: The entity that owns the thread, such as a user, organization, project, or any other domain entity in your application.
 
 Both identifiers are required for agents to store information:
 

package/dist/docs/references/docs-memory-working-memory.md

@@ -13,7 +13,7 @@ Working memory can persist at two different scopes:
 
 **Important:** Switching between scopes means the agent won't see memory from the other scope - thread-scoped memory is completely separate from resource-scoped memory.
 
-## Quick start
+## Quickstart
 
 Here's a minimal example of setting up an agent with working memory:
 

package/dist/docs/references/docs-observability-overview.md

@@ -19,7 +19,7 @@ The `DefaultExporter` persists traces to your configured storage backend. Not al
 
 For production environments with high traffic, we recommend using **ClickHouse** for the observability domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
 
-## Quick start
+## Quickstart
 
 Configure Observability in your Mastra instance:
 

package/dist/docs/references/docs-observability-tracing-exporters-arize.md

@@ -98,7 +98,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Quick Start with Docker:** Test locally with an in-memory Phoenix instance:
+> **Quickstart with Docker:** Test locally with an in-memory Phoenix instance:
 >
 > ```bash
 > docker run --pull=always -d --name arize-phoenix -p 6006:6006 \

package/dist/docs/references/docs-server-request-context.md

@@ -465,7 +465,7 @@ When you select a preset from the dropdown, the JSON editor populates with that
 
 ## Related
 
-- [Agent Request Context](https://mastra.ai/docs/agents/overview)
+- [Agent Request Context](https://mastra.ai/docs/memory/overview)
 - [Workflow Request Context](https://mastra.ai/docs/workflows/overview)
 - [Server Middleware](https://mastra.ai/docs/server/middleware)
 - [Authorization Middleware](https://mastra.ai/docs/server/middleware)

package/dist/docs/references/docs-workflows-overview.md

@@ -8,7 +8,7 @@ Workflows let you define complex sequences of tasks using clear, structured step
 
 Use workflows for tasks that are clearly defined upfront and involve multiple steps with a specific execution order. They give you fine-grained control over how data flows and transforms between steps, and which primitives are called at each stage.
 
-> **Watch an introduction:** An introduction to workflows, and how they compare to agents [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
+> **Tip:** Watch an introduction to workflows, and how they compare to agents on [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw).
 
 ## Core principles
 

package/dist/docs/references/docs-workspace-overview.md

@@ -56,7 +56,7 @@ const mastra = new Mastra({
 })
 ```
 
-### Agent-scoped workspace
+### Agent-level workspace
 
 Assign a workspace directly to an agent to override the global workspace:
 

package/dist/docs/references/guides-concepts-multi-agent-systems.md

@@ -0,0 +1,75 @@
+# Multi-agent systems
+
+A multi-agent system distributes a task across multiple agents instead of asking one agent to do everything. In Mastra, this usually means combining agents, workflows, or both so each part of the system has a clear role.
+
+The goal is to assign the right context, tools, and responsibilities to the right component. When that split is clear, a multi-agent system can be easier to reason about than one agent with a long prompt, many tools, and too many responsibilities.
+
+## When to use multi-agent systems
+
+Use a multi-agent system when one agent is no longer a good boundary for the work.
+
+This is often the case when:
+
+- A task spans different kinds of work, such as research, planning, writing, or review.
+- One agent would need too much context or too many tools.
+- Parts of the task should run in parallel.
+- Different stages need different prompts, models, or guardrails.
+- You want clear boundaries between routing, execution, and synthesis.
+
+Start with one agent when possible. Add more agents when the added structure clearly improves quality, speed, or reliability.
+
+Multi-agent patterns are useful when the system needs a clear way to divide context, decisions, and responsibilities across components. In practice, the key design question is which component stays in control as the task moves forward.
+
+## Handoffs
+
+A handoff pattern transfers control from one agent to another. Unlike a supervisor pattern, the first agent does not stay in charge for the full task. Instead, the active specialist takes ownership of the next part of the interaction.
+
+Use handoffs when the next specialist should continue the interaction directly instead of reporting back through a central coordinator. The tradeoff is that context management becomes more important, since the system must decide what the next agent inherits and what remains scoped.
+
+In Mastra, implement this pattern by combining [agents](https://mastra.ai/docs/agents/overview), [workflows](https://mastra.ai/docs/workflows/overview), and [memory](https://mastra.ai/docs/memory/overview). A workflow can route the task, but the defining feature of the pattern is that ownership moves to the next agent.
+
+## Workflows
+
+A workflow pattern defines the execution path in code. Instead of asking an agent to decide what happens next, you define the sequence through steps, branches, loops, and parallel blocks.
+
+Use workflows when the task is well understood and the execution path is known in advance. The main advantage is predictability: The system is easier to debug, reason about, and audit because the structure is explicit. The tradeoff is flexibility, since workflows are less adaptive when the task changes as it unfolds.
+
+In Mastra, [workflows](https://mastra.ai/docs/workflows/overview) can implement several coordination patterns, including handoffs and councils. What makes a workflow distinct is not which agents it calls, but that the control logic lives in the workflow itself.
+
+## Supervisors
+
+A supervisor pattern keeps one lead agent in control for the full task. The supervisor decides when to delegate, which specialist to call, what context to pass, and how to combine the result.
+
+Use this pattern when the task is open-ended and the full sequence is not known in advance. For example, a research task may require different lines of inquiry based on what earlier steps uncover. A supervisor can adapt as the task unfolds. The tradeoff is that the supervisor becomes the main coordination point. That makes the pattern flexible, but it also means the result depends heavily on good delegation behavior and clear subagent boundaries.
+
+In Mastra, this pattern maps directly to [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents). A supervisor agent defines subagents on the `agents` property and uses `stream()` or `generate()` to coordinate them. Mastra also provides delegation hooks, message filtering, and memory isolation to help control this pattern.
+
+> **Tip:** Follow the [supervisor agents tutorial](https://mastra.ai/guides/guide/research-coordinator) for a step-by-step guide.
+
+## Council
+
+A council pattern asks multiple agents to work on the same problem independently, then compares or synthesizes their outputs into one final answer. Unlike a supervisor, which divides the problem into parts, a council keeps the problem shared and brings multiple viewpoints to the same question.
+
+Use this pattern when the question is ambiguous, evaluative, or high-stakes and answer quality matters more than speed. The tradeoff is cost, since councils intentionally duplicate effort and usually take longer and use more tokens than other patterns.
+
+Mastra does not provide a dedicated council primitive. In Mastra, implement this pattern with [agents](https://mastra.ai/docs/agents/overview) and [workflows](https://mastra.ai/docs/workflows/overview): Run multiple agents in parallel, collect their outputs, and add a final synthesis or review step. Workflow control flow methods such as `.parallel()` provide the structure for this pattern.
+
+## Choosing a pattern
+
+These patterns differ mainly in how they distribute control:
+
+| Pattern           | Who stays in control | Use when                                         | Tradeoff                                                 | Mastra implementation                                                |
+| ----------------- | -------------------- | ------------------------------------------------ | -------------------------------------------------------- | -------------------------------------------------------------------- |
+| Handoffs          | Current specialist   | Ownership should move between specialists        | Context transfer becomes more important                  | Agents with workflows and memory                                     |
+| Workflows         | Execution graph      | The path is known in advance                     | Less adaptive when the task changes                      | [Workflows](https://mastra.ai/docs/workflows/overview)               |
+| Supervisor agents | One lead agent       | The task needs dynamic delegation                | Results depend on good coordination and clear boundaries | [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) |
+| Council           | Final synthesis step | The task needs multiple independent perspectives | Higher cost and latency                                  | Agents with workflow parallelism                                     |
+
+In practice, these patterns are often combined:
+
+- A workflow can contain one or more supervisor-driven steps.
+- A handoff flow can begin with a routing workflow.
+- A council can run inside a workflow and feed into a final approval step.
+- A supervisor can delegate to a workflow for a task with fixed internal structure.
+
+Choose the pattern based on the coordination problem, not the task label.

package/dist/docs/references/reference-agents-agent.md

@@ -6,6 +6,8 @@ The `Agent` class is the foundation for creating AI agents in Mastra. It provide
 
 ### Basic string instructions
 
+Passing instructions as a string or array of strings is the simplest way to set up an agent. This is useful for straightforward use cases where you just need to provide a prompt without additional configuration.
+
 ```typescript
 import { Agent } from '@mastra/core/agent'
 
@@ -40,9 +42,9 @@ export const agent3 = new Agent({
 })
 ```
 
-### Single `CoreSystemMessage`
+### Provider-specific configurations
 
-Use CoreSystemMessage format to access additional properties like `providerOptions` for provider-specific configurations:
+Each model provider also enables a few different options, including prompt caching and configuring reasoning. You can set `providerOptions` on the instruction level to set different caching strategy per system instruction/prompt.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -63,7 +65,7 @@ export const agent = new Agent({
 })
 ```
 
-### Multiple `CoreSystemMessages`
+### Mixed instruction formats
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -134,8 +136,4 @@ export const agent = new Agent({
 
 ## Returns
 
-**agent** (`Agent<TAgentId, TTools>`): A new Agent instance with the specified configuration.
-
-## Related
-
-- [Agents overview](https://mastra.ai/docs/agents/overview)
+**agent** (`Agent<TAgentId, TTools>`): A new Agent instance with the specified configuration.

package/dist/docs/references/reference-agents-generate.md

@@ -2,46 +2,103 @@
 
 The `.generate()` method enables non-streaming response generation from an agent with enhanced capabilities. It accepts messages and optional generation options.
 
-## Usage example
+## Usage examples
 
-```typescript
-// Basic usage
+### Basic usage
+
+Call the agent with a message to generate a response:
+
+```ts
 const result = await agent.generate('message for agent')
+```
+
+### With model settings
 
-// With model settings (e.g., limiting output tokens)
+Example of limiting output tokens and setting temperature:
+
+```ts
 const limitedResult = await agent.generate('Write a short poem about coding', {
   modelSettings: {
     maxOutputTokens: 50,
     temperature: 0.7,
   },
 })
+```
 
-// With structured output
-const structuredResult = await agent.generate("Extract the user's name and age", {
-  structuredOutput: {
-    schema: z.object({
-      name: z.string(),
-      age: z.number(),
-    }),
-  },
-})
+### With memory
 
-// With memory for conversation persistence
+Give your agent access to conversation history and persistence by configuring memory options. This allows the agent to remember previous interactions and maintain context across messages.
+
+```ts
 const memoryResult = await agent.generate('Remember my favorite color is blue', {
   memory: {
     thread: 'user-123-thread',
     resource: 'user-123',
   },
 })
+```
+
+### Accessing response headers
 
-// Accessing response headers
+Some model providers return useful information in response headers, such as remaining token counts or rate limit status. You can access these headers from the result object after generation completes.
+
+```ts
 const result = await agent.generate('Hello!')
 const remainingRequests = result.response?.headers?.['anthropic-ratelimit-requests-remaining']
 const remainingTokens = result.response?.headers?.['x-ratelimit-remaining-tokens']
 console.log(`Remaining requests: ${remainingRequests}, Remaining tokens: ${remainingTokens}`)
 ```
 
-> **Info:** **Model Compatibility**: This method requires AI SDK v5+ models. If you're using AI SDK v4 models, use the [`.generateLegacy()`](https://mastra.ai/reference/agents/generateLegacy) method instead. The framework automatically detects your model version and will throw an error if there's a mismatch.
+### Analyzing 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.
+
+```typescript
+const response = await agent.generate([
+  {
+    role: 'user',
+    content: [
+      {
+        type: 'image',
+        image: 'https://placebear.com/cache/395-205.jpg',
+        mimeType: 'image/jpeg',
+      },
+      {
+        type: 'text',
+        text: 'Describe the image in detail, and extract all the text in the image.',
+      },
+    ],
+  },
+])
+
+console.log(response.text)
+```
+
+### Using `maxSteps`
+
+The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make. Each step includes generating a response, executing any tool calls, and processing the result. Limiting steps helps prevent infinite loops, reduce latency, and control token usage for agents that use tools. The default is 5, but can be increased:
+
+```typescript
+const response = await agent.generate('Help me organize my day', {
+  maxSteps: 10,
+})
+
+console.log(response.text)
+```
+
+### Using `onStepFinish`
+
+You can monitor the progress of multi-step operations using the `onStepFinish` callback. This is useful for debugging or providing progress updates to users.
+
+`onStepFinish` is only available when streaming or generating text without structured output.
+
+```typescript
+const response = await agent.generate('Help me organize my day', {
+  onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
+    console.log({ text, toolCalls, toolResults, finishReason, usage })
+  },
+})
+```
 
 ## Parameters
 
@@ -313,10 +370,4 @@ console.log(`Remaining requests: ${remainingRequests}, Remaining tokens: ${remai
 
 **tripwire** (`StepTripwireData`): Tripwire data if content was blocked by a processor.
 
-**scoringData** (`object`): Scoring data for evals when \`returnScorerData\` is enabled.
-
-## Related
-
-- [Agent Networks](https://mastra.ai/docs/agents/networks) - Using the supervisor pattern for multi-agent coordination
-- [Migration: .network() to Supervisor Pattern](https://mastra.ai/guides/migrations/network-to-supervisor)
-- [Guide: Research Coordinator](https://mastra.ai/guides/guide/research-coordinator)
+**scoringData** (`object`): Scoring data for evals when \`returnScorerData\` is enabled.

package/dist/docs/references/reference-agents-getMemory.md

@@ -28,5 +28,5 @@ await agent.getMemory({
 
 ## Related
 
-- [Agent memory](https://mastra.ai/docs/agents/agent-memory)
+- [Memory](https://mastra.ai/docs/memory/overview)
 - [Request Context](https://mastra.ai/docs/server/request-context)

package/dist/docs/references/reference-agents-network.md

@@ -1,9 +1,9 @@
 # Agent.network()
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use the [supervisor pattern](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
-
 The `.network()` method enables multi-agent collaboration and routing. This method accepts messages and optional execution options.
 
+> **Deprecated:** The `.network()` primitive has been deprecated and will be removed in a future major release. Use [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+
 ## Usage example
 
 ```typescript

package/dist/docs/references/reference-ai-sdk-network-route.md

@@ -1,6 +1,6 @@
 # networkRoute()
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use the [supervisor pattern](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
 Creates a network route handler for streaming network execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts messages, executes an agent network, and streams the response back to the client in AI SDK-compatible format. Agent networks allow a routing agent to delegate tasks to other agents. You have to use it inside a [custom API route](https://mastra.ai/docs/server/custom-api-routes).