@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

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

@@ -0,0 +1,273 @@
+# Structured Output
+
+Structured output lets an agent return an object that matches the shape defined by a schema instead of returning text. The schema tells the model what fields to produce, and the model ensures the final result fits that shape.
+
+## When to use structured output
+
+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
+
+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.
+
+**Zod**:
+
+Define the `output` shape using [Zod](https://zod.dev/):
+
+```typescript
+import { z } from 'zod'
+
+const response = await testAgent.generate('Help me plan my day.', {
+  structuredOutput: {
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string()),
+      }),
+    ),
+  },
+})
+
+console.log(response.object)
+```
+
+**JSON Schema**:
+
+You can also use JSON Schema to define your output structure:
+
+```typescript
+const response = await testAgent.generate('Help me plan my day.', {
+  structuredOutput: {
+    schema: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          activities: {
+            type: 'array',
+            items: { type: 'string' },
+          },
+        },
+        required: ['name', 'activities'],
+      },
+    },
+  },
+})
+
+console.log(response.object)
+```
+
+> **Info:** 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.
+
+```json
+[
+  {
+    "name": "Morning Routine",
+    "activities": ["Wake up at 7am", "Exercise", "Shower", "Breakfast"]
+  },
+  {
+    "name": "Work",
+    "activities": ["Check emails", "Team meeting", "Lunch break"]
+  },
+  {
+    "name": "Evening",
+    "activities": ["Dinner", "Relax", "Read a book", "Sleep by 10pm"]
+  }
+]
+```
+
+## Streaming
+
+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.
+
+```typescript
+import { z } from 'zod'
+
+const stream = await testAgent.stream('Help me plan my day.', {
+  structuredOutput: {
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string()),
+      }),
+    ),
+  },
+})
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'object-result') {
+    console.log('\n', JSON.stringify(chunk, null, 2))
+  }
+  process.stdout.write(JSON.stringify(chunk))
+}
+
+console.log(await stream.object)
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+## Structuring agent
+
+When your main agent isn't proficient at creating structured output you can provide a `model` to `structuredOutput`. In this case, Mastra uses a second agent under the hood to extract structured data from the main agent's natural language response. This makes two LLM calls, one to generate the response and another to turn that response into the structured object, which adds some latency and cost but can improve accuracy for complex structuring tasks.
+
+```typescript
+import { z } from 'zod'
+
+const response = await testAgent.generate('Analyze the TypeScript programming language.', {
+  structuredOutput: {
+    schema: z.object({
+      overview: z.string(),
+      strengths: z.array(z.string()),
+      weaknesses: z.array(z.string()),
+      useCases: z.array(
+        z.object({
+          scenario: z.string(),
+          reasoning: z.string(),
+        }),
+      ),
+      comparison: z.object({
+        similarTo: z.array(z.string()),
+        differentiators: z.array(z.string()),
+      }),
+    }),
+    model: 'openai/gpt-4o',
+  },
+})
+
+console.log(response.object)
+```
+
+## Combining 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.
+
+If your tools aren't being called when structured output is enabled, or you receive an error when combining both features, try one of the workarounds below.
+
+### Workaround options
+
+When your model doesn't support tools and structured output together, you have three options:
+
+1. **Use `jsonPromptInjection: true`** - Injects the schema into the prompt instead of using the API's `response_format` parameter
+2. **Use a separate structuring model** - Pass a `model` to `structuredOutput` to use a second LLM for structuring
+3. **Use `prepareStep`** - Handle tools and structured output in separate steps
+
+Each approach is detailed in the sections below.
+
+## LLM structured output support
+
+Structured output support varies across LLMs due to differences in their APIs. The sections below cover workarounds for models that don't fully support structured output or combining it with tools.
+
+### `jsonPromptInjection`
+
+By default, Mastra passes the schema to the model provider using the `response_format` API parameter. Most model providers have built-in support for this, which reliably enforces the schema.
+
+If your model provider doesn't support `response_format`, you'll get an error from the API. When this happens, set `jsonPromptInjection: true`. This adds the schema to the system prompt instead, instructing the model to output JSON. This is less reliable than the API parameter approach.
+
+```typescript
+import { z } from 'zod'
+
+const response = await testAgent.generate('Help me plan my day.', {
+  structuredOutput: {
+    schema: z.array(
+      z.object({
+        name: z.string(),
+        activities: z.array(z.string()),
+      }),
+    ),
+    jsonPromptInjection: true,
+  },
+})
+
+console.log(response.object)
+```
+
+> **Gemini 2.5 with tools:** Gemini 2.5 models do not support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error `Function calling with a response mime type: 'application/json' is unsupported`.
+>
+> ```typescript
+> const response = await agentWithTools.generate('Your prompt', {
+>   structuredOutput: {
+>     schema: yourSchema,
+>     jsonPromptInjection: true, // Required for Gemini 2.5 when tools are present
+>   },
+> })
+> ```
+
+### Using 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.", {
+  structuredOutput: {
+    schema: yourSchema
+    model: 'openai/gpt-4o'
+  }
+});
+```
+
+### Multi-step approach with `prepareStep`
+
+For models that don't support tools and structured outputs together, you can use `prepareStep` to handle them in separate steps.
+
+```typescript
+const result = await agent.stream('weather in vancouver?', {
+  prepareStep: async ({ stepNumber }) => {
+    if (stepNumber === 0) {
+      return {
+        model: 'anthropic/claude-sonnet-4-20250514',
+        tools: {
+          weatherTool,
+        },
+        toolChoice: 'required',
+      }
+    }
+    return {
+      model: 'anthropic/claude-sonnet-4-20250514',
+      tools: undefined,
+      structuredOutput: {
+        schema: z.object({
+          temperature: z.number(),
+          humidity: z.number(),
+          windSpeed: z.number(),
+        }),
+      },
+    }
+  },
+})
+```
+
+## Error handling
+
+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({
+      summary: z.string(),
+      keyFeatures: z.array(z.string()),
+    }),
+    errorStrategy: 'fallback',
+    fallbackValue: {
+      summary: 'TypeScript is a typed superset of JavaScript',
+      keyFeatures: ['Static typing', 'Compiles to JavaScript', 'Better tooling'],
+    },
+  },
+})
+
+console.log(response.object)
+```
+
+## Related
+
+- [Using Tools](https://mastra.ai/docs/agents/using-tools)
+- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)

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

@@ -0,0 +1,304 @@
+# 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.
+
+## When to use supervisor agents
+
+Use supervisor agents when a task requires multiple agents with different specializations to work together. The supervisor handles delegation decisions, context passing, and result synthesis.
+
+Common use cases:
+
+- Research and writing workflows where one agent gathers data and another produces content
+- Multi-step tasks that need different expertise at each stage
+- Tasks where you need fine-grained control over delegation behavior
+
+## Quick start
+
+Define subagents with clear descriptions, then create a supervisor agent that references them:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const researchAgent = new Agent({
+  id: 'research-agent',
+  description: 'Gathers factual information and returns bullet-point summaries.',
+  model: 'openai/gpt-4o-mini',
+})
+
+const writingAgent = new Agent({
+  id: 'writing-agent',
+  description: 'Transforms research into well-structured articles.',
+  model: 'openai/gpt-4o-mini',
+})
+
+const supervisor = new Agent({
+  id: 'supervisor',
+  instructions: `You coordinate research and writing using specialized agents.
+    Delegate to research-agent for facts, then writing-agent for content.`,
+  model: 'openai/gpt-5.1',
+  agents: { researchAgent, writingAgent },
+  memory: new Memory({
+    storage: new LibSQLStore({ id: 'storage', url: 'file:mastra.db' }),
+  }),
+})
+
+const stream = await supervisor.stream('Research AI in education and write an article', {
+  maxSteps: 10,
+})
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+## Delegation hooks
+
+Delegation hooks let you intercept, modify, or reject delegations as they happen. Configure them under the `delegation` option, either in the agent's `defaultOptions` or per-call.
+
+### onDelegationStart
+
+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
+
+```typescript
+const stream = await supervisor.stream('Research AI trends', {
+  maxSteps: 10,
+  delegation: {
+    onDelegationStart: async context => {
+      console.log(`Delegating to: ${context.primitiveId}`)
+
+      // Modify the prompt for a specific agent
+      if (context.primitiveId === 'research-agent') {
+        return {
+          proceed: true,
+          modifiedPrompt: `${context.prompt}\n\nFocus on 2024-2025 data.`,
+          modifiedMaxSteps: 5,
+        }
+      }
+
+      // Reject delegation after too many iterations
+      if (context.iteration > 8) {
+        return {
+          proceed: false,
+          rejectionReason: 'Max iterations reached. Synthesize current findings.',
+        }
+      }
+
+      return { proceed: true }
+    },
+  },
+})
+```
+
+The `context` object includes:
+
+| Property      | Description                               |
+| ------------- | ----------------------------------------- |
+| `primitiveId` | The ID of the subagent being delegated to |
+| `prompt`      | The prompt the supervisor is sending      |
+| `iteration`   | Current iteration number                  |
+
+### onDelegationComplete
+
+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
+
+```typescript
+const stream = await supervisor.stream('Research AI trends', {
+  maxSteps: 10,
+  delegation: {
+    onDelegationComplete: async context => {
+      console.log(`Completed: ${context.primitiveId}`)
+
+      // Bail on errors
+      if (context.error) {
+        context.bail()
+        return {
+          feedback: `Delegation to ${context.primitiveId} failed: ${context.error}. Try a different approach.`,
+        }
+      }
+    },
+  },
+})
+```
+
+The `context` object includes:
+
+| Property      | Description                          |
+| ------------- | ------------------------------------ |
+| `primitiveId` | The ID of the subagent that ran      |
+| `result`      | The subagent's response              |
+| `error`       | Error if the delegation failed       |
+| `bail()`      | Function to stop the supervisor loop |
+
+## Message filtering
+
+By default, subagents receive the full conversation context from the supervisor. Use `messageFilter` to control what messages are shared — for example, to remove sensitive data or limit context size.
+
+```typescript
+const stream = await supervisor.stream('Research AI trends', {
+  maxSteps: 10,
+  delegation: {
+    messageFilter: ({ messages, primitiveId, prompt }) => {
+      // Remove messages containing sensitive data
+      return messages
+        .filter(msg => {
+          const content =
+            typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
+          return !content.includes('confidential')
+        })
+        .slice(-10) // Only pass the last 10 messages
+    },
+  },
+})
+```
+
+The callback receives `messages` (the full conversation history), `primitiveId` (the subagent ID), and `prompt` (the delegation prompt). Return the filtered array of messages.
+
+## Iteration monitoring
+
+`onIterationComplete` is called after each iteration of the supervisor loop. Use it to log progress, inject feedback, or stop execution early.
+
+```typescript
+const stream = await supervisor.stream('Research AI trends', {
+  maxSteps: 10,
+  onIterationComplete: async context => {
+    console.log(`Iteration ${context.iteration}/${context.maxIterations}`)
+    console.log(`Finish reason: ${context.finishReason}`)
+
+    // Inject feedback to guide the agent
+    if (!context.text.includes('recommendations')) {
+      return {
+        continue: true,
+        feedback: 'Please include specific recommendations in your analysis.',
+      }
+    }
+
+    // Stop early when the response is sufficient
+    if (context.text.length > 1000 && context.finishReason === 'stop') {
+      return { continue: false }
+    }
+
+    return { continue: true }
+  },
+})
+```
+
+Return `{ continue: true }` to keep iterating, or `{ continue: false }` to stop. Include optional `feedback` to inject guidance into the conversation. When `feedback` is combined with `continue: false`, the model may get one final turn to produce a text response incorporating the feedback, but only if the current iteration is still active (e.g., after tool calls) — otherwise no extra turn is granted.
+
+## 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.
+
+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
+
+This ensures subagents have the context they need without cluttering their memory with the entire supervisor conversation.
+
+## 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.
+
+```typescript
+const sensitiveDataTool = createTool({
+  id: 'get-user-data',
+  requireApproval: true,
+  execute: async input => {
+    return await database.getUserData(input.userId)
+  },
+})
+
+const dataAgent = new Agent({
+  id: 'data-agent',
+  tools: { sensitiveDataTool },
+})
+
+const supervisor = new Agent({
+  id: 'supervisor',
+  agents: { dataAgent },
+  memory: new Memory(),
+})
+
+const stream = await supervisor.stream('Get data for user 123')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'tool-call-approval') {
+    console.log('Tool requires approval:', chunk.payload.toolName)
+  }
+}
+```
+
+## Task completion scoring
+
+Task completion scorers validate whether the task is complete after each iteration. If validation fails, the supervisor continues iterating. Feedback from failed scorers is included in the conversation context so subagents can see what was missing.
+
+```typescript
+import { createScorer } from '@mastra/core/evals'
+
+const taskCompleteScorer = createScorer({
+  id: 'task-complete',
+  name: 'Task Completeness',
+}).generateScore(async context => {
+  const text = (context.run.output || '').toString()
+  const hasAnalysis = text.includes('analysis')
+  const hasRecommendations = text.includes('recommendation')
+  return hasAnalysis && hasRecommendations ? 1 : 0
+})
+
+const stream = await supervisor.stream('Research AI in education', {
+  maxSteps: 10,
+  isTaskComplete: {
+    scorers: [taskCompleteScorer],
+    strategy: 'all',
+    onComplete: async result => {
+      console.log('Task complete:', result.complete)
+    },
+  },
+})
+```
+
+## Writing effective instructions
+
+Clear instructions are essential for effective delegation. Your supervisor's `instructions` should specify available resources, when to use each one, how to coordinate them, and success criteria.
+
+Each subagent should have a clear `description` that explains what it does, what format it returns, and when to use it. The supervisor uses these descriptions to make delegation decisions.
+
+```typescript
+const supervisor = new Agent({
+  instructions: `You coordinate research and writing tasks.
+
+Available resources:
+- researchAgent: Gathers factual data and sources (returns bullet points)
+- writingAgent: Transforms research into narrative content (returns full paragraphs)
+
+Delegation strategy:
+1. For research requests: Delegate to researchAgent first
+2. For writing requests: Delegate to writingAgent
+3. For complex requests: Delegate to researchAgent first, then writingAgent
+
+Success criteria:
+- All user questions are fully answered
+- Response is well-formatted and complete`,
+  agents: { researchAgent, writingAgent },
+})
+```
+
+## 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)