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

package/dist/docs/references/docs-agents-structured-output.md

@@ -6,7 +6,7 @@ Structured output lets an agent return an object that matches the shape defined
 
 Use structured output when you need an agent to return a data object rather than text. Having well defined fields can make it simpler to pull out the values you need for API calls, UI rendering, or application logic.
 
-## Defining schemas
+## Define schemas
 
 Agents can return structured data by defining the expected output with either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). Zod is recommended because it provides TypeScript type inference and runtime validation, while JSON Schema is useful when you need a language agnostic format.
 
@@ -58,11 +58,9 @@ const response = await testAgent.generate('Help me plan my day.', {
 console.log(response.object)
 ```
 
-> **Info:** Visit [.generate()](https://mastra.ai/reference/agents/generate) for a full list of configuration options.
+> **Note:** Visit [`.generate()`](https://mastra.ai/reference/agents/generate) for a full list of configuration options.
 
-### Example output
-
-The `response.object` will contain the structured data as defined by the schema.
+**Example output:** The `response.object` will contain the structured data as defined by the schema.
 
 ```json
 [
@@ -81,7 +79,7 @@ The `response.object` will contain the structured data as defined by the schema.
 ]
 ```
 
-## Streaming
+## Stream structured output
 
 Streaming also supports structured output. The final structured object is available on `stream.fullStream` and after the stream completes on `stream.object`. Text stream chunks are still emitted, but they contain natural language text rather than structured data.
 
@@ -144,7 +142,7 @@ const response = await testAgent.generate('Analyze the TypeScript programming la
 console.log(response.object)
 ```
 
-## Combining tools and structured output
+## Combine tools and structured output
 
 When an agent has both tools and structured output configured, some models may not support using both features together. This is a limitation of the underlying model APIs, not Mastra itself.
 
@@ -199,17 +197,17 @@ console.log(response.object)
 > })
 > ```
 
-### Using a separate structuring model
+### Use a separate structuring model
 
 When `model` is provided to the `structuredOutput` property, Mastra uses a separate internal agent to handle the structured output. The main agent will handle all of the steps (including tool calling) and the structured output model will handle only the generation of structured output.
 
 ```typescript
-const response = await testAgent.generate("Tell me about TypeScript.", {
+const response = await testAgent.generate('Tell me about TypeScript.', {
   structuredOutput: {
-    schema: yourSchema
-    model: 'openai/gpt-5.4'
-  }
-});
+    schema: yourSchema,
+    model: 'openai/gpt-5.4',
+  },
+})
 ```
 
 ### Multi-step approach with `prepareStep`
@@ -243,13 +241,11 @@ const result = await agent.stream('weather in vancouver?', {
 })
 ```
 
-## Error handling
+## Handle errors
 
 When schema validation fails, you can control how errors are handled using `errorStrategy`. The default `strict` strategy throws an error, while `warn` logs a warning and continues. The `fallback` strategy returns the values provided using `fallbackValue`.
 
 ```typescript
-import { z } from 'zod'
-
 const response = await testAgent.generate('Tell me about TypeScript.', {
   structuredOutput: {
     schema: z.object({
@@ -265,9 +261,4 @@ const response = await testAgent.generate('Tell me about TypeScript.', {
 })
 
 console.log(response.object)
-```
-
-## Related
-
-- [Using Tools](https://mastra.ai/docs/agents/using-tools)
-- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
+```

package/dist/docs/references/docs-agents-supervisor-agents.md

@@ -1,6 +1,8 @@
 # Supervisor agents
 
-A supervisor agent coordinates multiple subagents using `agent.stream()` or `agent.generate()`. You configure subagents on the supervisor's `agents` property, and the supervisor uses its instructions and each subagent's `description` to decide when and how to delegate tasks.
+**Added in:** `@mastra/core@1.8.0`
+
+A supervisor agent coordinates multiple subagents using [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) or [`Agent.generate()`](https://mastra.ai/reference/agents/generate). You configure subagents on the supervisor's `agents` property, and the supervisor uses its instructions and each subagent's `description` to decide when and how to delegate tasks.
 
 ## When to use supervisor agents
 
@@ -12,7 +14,9 @@ Common use cases:
 - Multi-step tasks that need different expertise at each stage
 - Tasks where you need fine-grained control over delegation behavior
 
-## Quick start
+> **Note:** Supervisor agents are one approach to building multi-agent systems in Mastra. For other patterns, read the [conceptual overview](https://mastra.ai/guides/concepts/multi-agent-systems).
+
+## Quickstart
 
 Define subagents with clear descriptions, then create a supervisor agent that references them:
 
@@ -61,10 +65,10 @@ Delegation hooks let you intercept, modify, or reject delegations as they happen
 
 Called before the supervisor delegates to a subagent. Return an object to control the delegation:
 
-- `proceed: true` — allow the delegation (default behavior)
-- `proceed: false` — reject the delegation with a `rejectionReason`
-- `modifiedPrompt` — rewrite the prompt sent to the subagent
-- `modifiedMaxSteps` — limit the subagent's iteration count
+- `proceed: true`: Allow the delegation (default behavior)
+- `proceed: false`: Reject the delegation with a `rejectionReason`
+- `modifiedPrompt`: Rewrite the prompt sent to the subagent
+- `modifiedMaxSteps`: Limit the subagent's iteration count
 
 ```typescript
 const stream = await supervisor.stream('Research AI trends', {
@@ -108,8 +112,8 @@ The `context` object includes:
 
 Called after a delegation finishes. Use it to inspect results, provide feedback, or stop execution:
 
-- `context.bail()` — stop the supervisor loop immediately
-- Return `{ feedback: '...' }` — add feedback that gets saved to the supervisor's memory and is visible to subsequent iterations
+- `context.bail()`: Stop the supervisor loop immediately
+- Return `{ feedback: '...' }`: Add feedback that gets saved to the supervisor's memory and is visible to subsequent iterations
 
 ```typescript
 const stream = await supervisor.stream('Research AI trends', {
@@ -196,16 +200,18 @@ Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop.
 
 ## Memory isolation
 
-The supervisor pattern implements memory isolation — subagents receive the full conversation context for better decision-making, but only their specific delegation prompt and response are saved to their memory.
+Supervisor agents implement memory isolation. Subagents receive the full conversation context for better decision-making, but only their specific delegation prompt and response are saved to their memory.
 
 How it works:
 
-1. **Full context forwarded** — When the supervisor delegates, the subagent receives all messages from the supervisor's conversation
-2. **Scoped memory saves** — Only the delegation prompt and the subagent's response are saved to the subagent's memory
-3. **Fresh thread per invocation** — Each delegation uses a unique thread ID, ensuring clean separation
+1. **Full context forwarded**: When the supervisor delegates, the subagent receives all messages from the supervisor's conversation
+2. **Scoped memory saves**: Only the delegation prompt and the subagent's response are saved to the subagent's memory
+3. **Fresh thread per invocation**: Each delegation uses a unique thread ID, ensuring clean separation
 
 This ensures subagents have the context they need without cluttering their memory with the entire supervisor conversation.
 
+> **Note:** Visit [memory in multi-agent systems](https://mastra.ai/docs/memory/overview) for more details.
+
 ## Tool approval propagation
 
 Tool approvals propagate through the delegation chain. When a subagent uses a tool with `requireApproval: true` or calls `suspend()`, the approval request surfaces to the supervisor level.
@@ -296,9 +302,9 @@ Success criteria:
 
 ## Related
 
-- [Agent Networks](https://mastra.ai/docs/agents/networks)
-- [Migration: .network() to Supervisor Pattern](https://mastra.ai/guides/migrations/network-to-supervisor)
-- [Guide: Research Coordinator](https://mastra.ai/guides/guide/research-coordinator)
-- [Agent.stream() Reference](https://mastra.ai/reference/streaming/agents/stream)
-- [Agent.generate() Reference](https://mastra.ai/reference/agents/generate)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Guide: Research coordinator](https://mastra.ai/guides/guide/research-coordinator)
+- [Agent.stream() reference](https://mastra.ai/reference/streaming/agents/stream)
+- [Agent.generate() reference](https://mastra.ai/reference/agents/generate)
+- [Agent approval](https://mastra.ai/docs/agents/agent-approval)
+- [Memory in multi-agent systems](https://mastra.ai/docs/memory/overview)
+- [Concept: Multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems)

package/dist/docs/references/docs-agents-using-tools.md

@@ -1,14 +1,14 @@
-# Using tools
+# Tools
 
 Agents use tools to call APIs, query databases, or run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
 
 ## When to use tools
 
-Use tools when an agent needs additional context or information from remote resources, or when it needs to run code that performs a specific operation. This includes tasks a model can't reliably handle on its own, such as fetching live data or returning consistent, well defined outputs.
+Use tools when an agent needs additional context or information from remote resources, or when it needs to run code that performs a specific operation. This includes tasks a model can't reliably handle on its own, such as fetching live data or returning consistent, well-defined outputs.
 
-## Creating a tool
+## Quickstart
 
-When creating tools, keep descriptions concise and focused on what the tool does, emphasizing its primary use case. Descriptive schema names can also help guide the agent on how to use the tool.
+Import [`createTool`](https://mastra.ai/reference/tools/create-tool) from `@mastra/core/tools` and define a tool with an `id`, `description`, `inputSchema`, `outputSchema`, and `execute` function.
 
 This example shows how to create a tool that fetches weather data from an API. When the agent calls the tool, it provides the required input as defined by the tool's `inputSchema`. The tool accesses this data through its `inputData` parameter, which in this example includes the `location` used in the weather API query.
 
@@ -36,45 +36,11 @@ export const weatherTool = createTool({
 })
 ```
 
-## Shaping output for the model
-
-Use `toModelOutput` when your tool returns rich structured data for your application, but you want the model to receive a smaller or multimodal representation. This keeps model context focused while preserving the full tool result in your app.
-
-```typescript
-export const weatherTool = createTool({
-  // ...other config
-  execute: async ({ location }) => {
-    const response = await fetch(`https://wttr.in/${location}?format=j1`)
-    const data = await response.json()
-
-    return {
-      location,
-      temperature: data.current_condition[0].temp_F,
-      condition: data.current_condition[0].weatherDesc[0].value,
-      weatherIconUrl: data.current_condition[0].weatherIconUrl[0].value,
-      source: data,
-    }
-  },
-  toModelOutput: output => {
-    return {
-      type: 'content',
-      value: [
-        {
-          type: 'text',
-          text: `${output.location}: ${output.temperature}F and ${output.condition}`,
-        },
-        { type: 'image-url', url: output.weatherIconUrl },
-      ],
-    }
-  },
-})
-```
-
-## Adding tools to an agent
+When creating tools, keep descriptions concise and focused on what the tool does, emphasizing its primary use case. Descriptive schema names can also help guide the agent on how to use the tool.
 
-To make a tool available to an agent, add it to `tools`. Mentioning available tools and their general purpose in the agent's system prompt helps the agent decide when to call a tool and when not to.
+> **Note:** Visit the [`createTool`](https://mastra.ai/reference/tools/create-tool) reference for more information on available properties, configurations, and examples.
 
-An agent can use multiple tools to handle more complex tasks by delegating specific parts to individual tools. The agent decides which tools to use based on the user's message, the agent's instructions, and the tool descriptions and schemas.
+To make a tool available to an agent, add it to the `tools` property on the `Agent` class. Mentioning available tools and their general purpose in the agent's system prompt helps the agent decide when to call a tool and when not to.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -84,60 +50,61 @@ export const weatherAgent = new Agent({
   id: 'weather-agent',
   name: 'Weather Agent',
   instructions: `
-      You are a helpful weather assistant.
-      Use the weatherTool to fetch current weather data.`,
+    You are a helpful weather assistant.
+    Use the weatherTool to fetch current weather data.`,
   model: 'openai/gpt-5.4',
   tools: { weatherTool },
 })
 ```
 
-## Using multiple tools
+## Multiple tools
 
-When multiple tools are available, the agent may choose to use one, several, or none, depending on what's needed to answer the query.
+An agent can use multiple tools to handle more complex tasks by delegating specific parts to individual tools. The agent decides which tools to use based on the user's message, the agent's instructions, and the tool descriptions and schemas.
 
 ```typescript
+import { Agent } from '@mastra/core/agent'
 import { weatherTool } from '../tools/weather-tool'
-import { activitiesTool } from '../tools/activities-tool'
+import { hazardsTool } from '../tools/hazards-tool'
 
 export const weatherAgent = new Agent({
   id: 'weather-agent',
   name: 'Weather Agent',
-  tools: { weatherTool, activitiesTool },
+  instructions: `
+    You are a helpful weather assistant.
+    Use the weatherTool to fetch current weather data.
+    Use the hazardsTool to provide information about potential weather hazards.`,
+  model: 'openai/gpt-5.4',
+  tools: { weatherTool, hazardsTool },
 })
 ```
 
-## Using agents as tools
+## Agents as tools
 
-Agents can be added to other agents through the `agents` configuration. When you add subagents, the parent agent becomes a supervisor. A supervisor can delegate tasks to subagents using the [supervisor pattern](https://mastra.ai/docs/agents/supervisor-agents), with support for delegation hooks, message filtering, iteration monitoring, and task completion scoring. Mastra automatically converts each subagent to a tool that the parent agent can call, named `agent-<agentName>`.
+Add subagents through the `agents` configuration to create a [supervisor](https://mastra.ai/docs/agents/supervisor-agents). Mastra converts each subagent to a tool named `agent-<key>`. Include a `description` on each subagent so the supervisor knows when to delegate.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
 
-export const parentAgent = new Agent({
-  id: 'parent-agent',
-  name: 'Parent Agent',
-  description: 'Take care in writing a good description here',
-  instructions: `Instructions`,
+const writer = new Agent({
+  id: 'writer',
+  name: 'Writer',
+  description: 'Drafts and edits written content',
+  instructions: 'You are a skilled writer.',
   model: 'openai/gpt-5.4',
-  agents: {
-    subAgent,
-  },
 })
 
-const subAgent = new Agent({
-  id: 'sub-agent',
-  name: 'Sub Agent',
-  description: 'Take care in writing a good description here',
-  instructions: `Instructions`,
+export const supervisor = new Agent({
+  id: 'supervisor',
+  name: 'Supervisor',
+  instructions: 'Coordinate the writer to produce content.',
   model: 'openai/gpt-5.4',
+  agents: { writer },
 })
 ```
 
-The subagent should include a `description` to help the parent agent understand when to use it. See the [`toolName` docs](#subagents-and-workflows-as-tools) to learn more about the tool naming scheme.
-
-## Using workflows as tools
+## Workflows as tools
 
-Workflows can be added to agents through the `workflows` configuration. When you add a workflow, Mastra automatically converts it to a tool that the agent can call. The generated tool is named `workflow-<workflowName>` and uses the workflow's `inputSchema` and `outputSchema`.
+Add workflows through the `workflows` configuration. Mastra converts each workflow to a tool named `workflow-<key>`, using the workflow's `inputSchema` and `outputSchema`. Include a `description` on the workflow so the agent knows when to trigger it.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -146,53 +113,66 @@ import { researchWorkflow } from '../workflows/research-workflow'
 export const researchAgent = new Agent({
   id: 'research-agent',
   name: 'Research Agent',
-  instructions: `
-      You are a research assistant.
-      Use the research workflow to gather and compile information on topics.`,
+  instructions: 'You are a research assistant.',
   model: 'openai/gpt-5.4',
-  tools: {
-    weatherTool,
-  },
-  workflows: {
-    researchWorkflow,
-  },
+  workflows: { researchWorkflow },
 })
 ```
 
-The workflow should include a `description` to help the agent understand when to use it:
+## Shape output for the model
+
+Use `toModelOutput` when your tool returns rich structured data for your application, but you want the model to receive a smaller or multimodal representation. This keeps model context focused while preserving the full tool result in your app.
 
 ```typescript
-import { createWorkflow } from '@mastra/core/workflows'
-import { z } from 'zod'
+export const weatherTool = createTool({
+  execute: async ({ location }) => {
+    const response = await fetch(`https://wttr.in/${location}?format=j1`)
+    const data = await response.json()
 
-export const researchWorkflow = createWorkflow({
-  id: 'research-workflow',
-  description: 'Gathers information on a topic and compiles a summary report.',
-  // Rest of the workflow...
-}).commit()
+    return {
+      location,
+      temperature: data.current_condition[0].temp_F,
+      condition: data.current_condition[0].weatherDesc[0].value,
+      weatherIconUrl: data.current_condition[0].weatherIconUrl[0].value,
+      source: data,
+    }
+  },
+  toModelOutput: output => {
+    return {
+      type: 'content',
+      value: [
+        {
+          type: 'text',
+          text: `${output.location}: ${output.temperature}F and ${output.condition}`,
+        },
+        { type: 'image-url', url: output.weatherIconUrl },
+      ],
+    }
+  },
+})
 ```
 
-When the agent calls the workflow tool, it receives a response containing the workflow result and a `runId` that can be used to track the execution:
+## Control tool selection
+
+Pass `toolChoice` or `activeTools` to `.generate()` or `.stream()` to control which tools the agent uses at runtime.
 
 ```typescript
-{
-  result: { summary: "...", sources: ["..."] },
-  runId: "abc-123"
-}
+await agent.generate('Check the forecast', {
+  toolChoice: 'required',
+  activeTools: ['weatherTool'],
+})
 ```
 
-See the [`toolName` docs](#subagents-and-workflows-as-tools) to learn more about the tool naming scheme.
+> **Note:** See the [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate) for all runtime options including `toolsets`, `clientTools`, and `prepareStep`.
 
-## Controlling `toolName` in stream responses
+## Control `toolName` in stream responses
 
 The `toolName` in stream responses is determined by the **object key** you use, not the `id` property of the tool, agent, or workflow.
 
 ```typescript
-// Tool defined with id: "weather-tool"
 export const weatherTool = createTool({
-  id: "weather-tool",
-  // ...
-});
+  id: 'weather-tool',
+})
 
 // Using the variable name as the key
 tools: { weatherTool }
@@ -234,15 +214,12 @@ Note that for subagents, you'll see two different identifiers in stream response
 - `toolName: "agent-weather"` in tool call events — the generated tool wrapper name
 - `id: "weather-agent"` in `data-tool-agent` chunks — the subagent's actual `id` property
 
-## Tools with structured output
-
-When using tools with [structured output](https://mastra.ai/docs/agents/structured-output), some models don't support combining both features in the same API call. If your tools aren't being called when structured output is enabled, or you receive errors about incompatible options, see [Combining tools and structured output](https://mastra.ai/docs/agents/structured-output) for model compatibility information and workarounds.
-
 ## Related
 
-- [MCP Overview](https://mastra.ai/docs/mcp/overview)
-- [Dynamic Tool Search](https://mastra.ai/reference/processors/tool-search-processor) - Load tools on demand for agents with large tool libraries
-- [Structured Output](https://mastra.ai/docs/agents/structured-output)
-- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
-- [Supervisor Agents](https://mastra.ai/docs/agents/supervisor-agents)
-- [Request Context](https://mastra.ai/docs/server/request-context)
+- [`createTool` reference](https://mastra.ai/reference/tools/create-tool)
+- [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate): Runtime options for tool selection, steps, and callbacks
+- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [Dynamic tool search](https://mastra.ai/reference/processors/tool-search-processor): Load tools on demand for agents with large tool libraries
+- [Tools with structured output](https://mastra.ai/docs/agents/structured-output): Model compatibility when combining tools and structured output
+- [Agent approval](https://mastra.ai/docs/agents/agent-approval)
+- [Request context](https://mastra.ai/docs/server/request-context)

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

@@ -1,10 +1,10 @@
-# Observational memory
+# Observational Memory
 
 **Added in:** `@mastra/memory@1.1.0`
 
 Observational Memory (OM) is Mastra's memory system for long-context agentic memory. Two background agents — an **Observer** and a **Reflector** — watch your agent's conversations and maintain a dense observation log that replaces raw message history as it grows.
 
-## Quick start
+## Quickstart
 
 Enable `observationalMemory` in the memory options when creating your agent:
 
@@ -75,6 +75,8 @@ Date: 2026-01-15
 
 The compression is typically 5–40×. The Observer also tracks a **current task** and **suggested response** so the agent picks up where it left off.
 
+If you enable `observation.threadTitle`, the Observer can also suggest a short thread title when the conversation topic meaningfully changes. Thread title generation is opt-in and updates the thread metadata, so apps like Mastra Code can show the latest title in thread lists and status UI.
+
 Example: an agent using Playwright MCP might see 50,000+ tokens per page snapshot. With OM, the Observer watches the interaction and creates a few hundred tokens of observations about what was on the page and what actions were taken. The agent stays on task without carrying every raw snapshot.
 
 ### Reflections