@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/models/providers/zhipuai.md

@@ -0,0 +1,79 @@
+# ![Zhipu AI logo](https://models.dev/logos/zhipuai.svg)Zhipu AI
+
+Access 9 Zhipu AI models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
+
+Learn more in the [Zhipu AI documentation](https://docs.z.ai/guides/overview/pricing).
+
+```bash
+ZHIPU_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "zhipuai/glm-4.5"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Zhipu AI documentation](https://docs.z.ai/guides/overview/pricing) for details.
+
+## Models
+
+| Model                   | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ----------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `zhipuai/glm-4.5`       | 131K    |       |           |       |       |       | $0.60      | $2          |
+| `zhipuai/glm-4.5-air`   | 131K    |       |           |       |       |       | $0.20      | $1          |
+| `zhipuai/glm-4.5-flash` | 131K    |       |           |       |       |       | —          | —           |
+| `zhipuai/glm-4.5v`      | 64K     |       |           |       |       |       | $0.60      | $2          |
+| `zhipuai/glm-4.6`       | 205K    |       |           |       |       |       | $0.60      | $2          |
+| `zhipuai/glm-4.6v`      | 128K    |       |           |       |       |       | $0.30      | $0.90       |
+| `zhipuai/glm-4.7`       | 205K    |       |           |       |       |       | $0.60      | $2          |
+| `zhipuai/glm-4.7-flash` | 200K    |       |           |       |       |       | —          | —           |
+| `zhipuai/glm-5`         | 205K    |       |           |       |       |       | $1         | $3          |
+
+## Advanced Configuration
+
+### Custom Headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://open.bigmodel.cn/api/paas/v4",
+    id: "zhipuai/glm-4.5",
+    apiKey: process.env.ZHIPU_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic Model Selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "zhipuai/glm-5"
+      : "zhipuai/glm-4.5";
+  }
+});
+```

package/.docs/models/providers.md

@@ -0,0 +1,81 @@
+# Model Providers
+
+Direct access to individual AI model providers. Each provider offers unique models with specific capabilities and pricing.
+
+- [OpenAI](https://mastra.ai/models/providers/openai)
+- [Anthropic](https://mastra.ai/models/providers/anthropic)
+- [Google](https://mastra.ai/models/providers/google)
+- [DeepSeek](https://mastra.ai/models/providers/deepseek)
+- [Groq](https://mastra.ai/models/providers/groq)
+- [Mistral](https://mastra.ai/models/providers/mistral)
+- [xAI](https://mastra.ai/models/providers/xai)
+- [302.AI](https://mastra.ai/models/providers/302ai)
+- [Abacus](https://mastra.ai/models/providers/abacus)
+- [AIHubMix](https://mastra.ai/models/providers/aihubmix)
+- [Alibaba](https://mastra.ai/models/providers/alibaba)
+- [Alibaba (China)](https://mastra.ai/models/providers/alibaba-cn)
+- [Bailing](https://mastra.ai/models/providers/bailing)
+- [Baseten](https://mastra.ai/models/providers/baseten)
+- [Berget.AI](https://mastra.ai/models/providers/berget)
+- [Cerebras](https://mastra.ai/models/providers/cerebras)
+- [Chutes](https://mastra.ai/models/providers/chutes)
+- [Cloudflare Workers AI](https://mastra.ai/models/providers/cloudflare-workers-ai)
+- [Cortecs](https://mastra.ai/models/providers/cortecs)
+- [Deep Infra](https://mastra.ai/models/providers/deepinfra)
+- [FastRouter](https://mastra.ai/models/providers/fastrouter)
+- [Fireworks AI](https://mastra.ai/models/providers/fireworks-ai)
+- [Firmware](https://mastra.ai/models/providers/firmware)
+- [Friendli](https://mastra.ai/models/providers/friendli)
+- [GitHub Models](https://mastra.ai/models/providers/github-models)
+- [Helicone](https://mastra.ai/models/providers/helicone)
+- [Hugging Face](https://mastra.ai/models/providers/huggingface)
+- [iFlow](https://mastra.ai/models/providers/iflowcn)
+- [Inception](https://mastra.ai/models/providers/inception)
+- [Inference](https://mastra.ai/models/providers/inference)
+- [IO.NET](https://mastra.ai/models/providers/io-net)
+- [Jiekou.AI](https://mastra.ai/models/providers/jiekou)
+- [Kilo Gateway](https://mastra.ai/models/providers/kilo)
+- [Kimi For Coding](https://mastra.ai/models/providers/kimi-for-coding)
+- [KUAE Cloud Coding Plan](https://mastra.ai/models/providers/kuae-cloud-coding-plan)
+- [Llama](https://mastra.ai/models/providers/llama)
+- [LMStudio](https://mastra.ai/models/providers/lmstudio)
+- [LucidQuery AI](https://mastra.ai/models/providers/lucidquery)
+- [MiniMax (minimax.io)](https://mastra.ai/models/providers/minimax)
+- [MiniMax (minimaxi.com)](https://mastra.ai/models/providers/minimax-cn)
+- [MiniMax Coding Plan (minimax.io)](https://mastra.ai/models/providers/minimax-coding-plan)
+- [MiniMax Coding Plan (minimaxi.com)](https://mastra.ai/models/providers/minimax-cn-coding-plan)
+- [Moark](https://mastra.ai/models/providers/moark)
+- [ModelScope](https://mastra.ai/models/providers/modelscope)
+- [Moonshot AI](https://mastra.ai/models/providers/moonshotai)
+- [Moonshot AI (China)](https://mastra.ai/models/providers/moonshotai-cn)
+- [Morph](https://mastra.ai/models/providers/morph)
+- [NanoGPT](https://mastra.ai/models/providers/nano-gpt)
+- [Nebius Token Factory](https://mastra.ai/models/providers/nebius)
+- [Nova](https://mastra.ai/models/providers/nova)
+- [NovitaAI](https://mastra.ai/models/providers/novita-ai)
+- [Nvidia](https://mastra.ai/models/providers/nvidia)
+- [Ollama Cloud](https://mastra.ai/models/providers/ollama-cloud)
+- [OpenCode Zen](https://mastra.ai/models/providers/opencode)
+- [OVHcloud AI Endpoints](https://mastra.ai/models/providers/ovhcloud)
+- [Perplexity](https://mastra.ai/models/providers/perplexity)
+- [Poe](https://mastra.ai/models/providers/poe)
+- [Privatemode AI](https://mastra.ai/models/providers/privatemode-ai)
+- [Requesty](https://mastra.ai/models/providers/requesty)
+- [Scaleway](https://mastra.ai/models/providers/scaleway)
+- [SiliconFlow](https://mastra.ai/models/providers/siliconflow)
+- [SiliconFlow (China)](https://mastra.ai/models/providers/siliconflow-cn)
+- [STACKIT](https://mastra.ai/models/providers/stackit)
+- [StepFun](https://mastra.ai/models/providers/stepfun)
+- [submodel](https://mastra.ai/models/providers/submodel)
+- [Synthetic](https://mastra.ai/models/providers/synthetic)
+- [Together AI](https://mastra.ai/models/providers/togetherai)
+- [Upstage](https://mastra.ai/models/providers/upstage)
+- [Vivgrid](https://mastra.ai/models/providers/vivgrid)
+- [Vultr](https://mastra.ai/models/providers/vultr)
+- [Weights & Biases](https://mastra.ai/models/providers/wandb)
+- [Xiaomi](https://mastra.ai/models/providers/xiaomi)
+- [Z.AI](https://mastra.ai/models/providers/zai)
+- [Z.AI Coding Plan](https://mastra.ai/models/providers/zai-coding-plan)
+- [ZenMux](https://mastra.ai/models/providers/zenmux)
+- [Zhipu AI](https://mastra.ai/models/providers/zhipuai)
+- [Zhipu AI Coding Plan](https://mastra.ai/models/providers/zhipuai-coding-plan)

package/.docs/reference/agents/agent.md

@@ -0,0 +1,141 @@
+# Agent Class
+
+The `Agent` class is the foundation for creating AI agents in Mastra. It provides methods for generating responses, streaming interactions, and handling voice capabilities.
+
+## Usage examples
+
+### Basic string instructions
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+// String instructions
+export const agent = new Agent({
+  id: 'test-agent',
+  name: 'Test Agent',
+  instructions: 'You are a helpful assistant that provides concise answers.',
+  model: 'openai/gpt-5.1',
+})
+
+// System message object
+export const agent2 = new Agent({
+  id: 'test-agent-2',
+  name: 'Test Agent 2',
+  instructions: {
+    role: 'system',
+    content: 'You are an expert programmer',
+  },
+  model: 'openai/gpt-5.1',
+})
+
+// Array of system messages
+export const agent3 = new Agent({
+  id: 'test-agent-3',
+  name: 'Test Agent 3',
+  instructions: [
+    { role: 'system', content: 'You are a helpful assistant' },
+    { role: 'system', content: 'You have expertise in TypeScript' },
+  ],
+  model: 'openai/gpt-5.1',
+})
+```
+
+### Single CoreSystemMessage
+
+Use CoreSystemMessage format to access additional properties like `providerOptions` for provider-specific configurations:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const agent = new Agent({
+  id: 'core-message-agent',
+  name: 'Core Message Agent',
+  instructions: {
+    role: 'system',
+    content: 'You are a helpful assistant specialized in technical documentation.',
+    providerOptions: {
+      openai: {
+        reasoningEffort: 'low',
+      },
+    },
+  },
+  model: 'openai/gpt-5.1',
+})
+```
+
+### Multiple CoreSystemMessages
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+// This could be customizable based on the user
+const preferredTone = {
+  role: 'system',
+  content: 'Always maintain a professional and empathetic tone.',
+}
+
+export const agent = new Agent({
+  id: 'multi-message-agent',
+  name: 'Multi Message Agent',
+  instructions: [
+    { role: 'system', content: 'You are a customer service representative.' },
+    preferredTone,
+    {
+      role: 'system',
+      content: 'Escalate complex issues to human agents when needed.',
+      providerOptions: {
+        anthropic: { cacheControl: { type: 'ephemeral' } },
+      },
+    },
+  ],
+  model: 'anthropic/claude-sonnet-4-20250514',
+})
+```
+
+## Constructor parameters
+
+**id?:** (`string`): Unique identifier for the agent. Defaults to \`name\` if not provided.
+
+**name:** (`string`): Display name for the agent. Used as the identifier if \`id\` is not provided.
+
+**description?:** (`string`): Optional description of the agent's purpose and capabilities.
+
+**instructions:** (`SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise<SystemMessage>`): Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, array of system messages, or a function that returns any of these types dynamically. SystemMessage types: string | string\[] | CoreSystemMessage | CoreSystemMessage\[] | SystemModelMessage | SystemModelMessage\[]
+
+**model:** (`MastraLanguageModel | ({ requestContext: RequestContext }) => MastraLanguageModel | Promise<MastraLanguageModel>`): The language model used by the agent. Can be provided statically or resolved at runtime.
+
+**agents?:** (`Record<string, Agent> | ({ requestContext: RequestContext }) => Record<string, Agent> | Promise<Record<string, Agent>>`): Subagents that the agent can access. Can be provided statically or resolved dynamically.
+
+**tools?:** (`ToolsInput | ({ requestContext: RequestContext }) => ToolsInput | Promise<ToolsInput>`): Tools that the agent can access. Can be provided statically or resolved dynamically.
+
+**workflows?:** (`Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>`): Workflows that the agent can execute. Can be static or dynamically resolved.
+
+**defaultOptions?:** (`AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>`): Default options used when calling \`stream()\` and \`generate()\`.
+
+**defaultGenerateOptionsLegacy?:** (`AgentGenerateOptions | ({ requestContext: RequestContext }) => AgentGenerateOptions | Promise<AgentGenerateOptions>`): Default options used when calling \`generateLegacy()\`.
+
+**defaultStreamOptionsLegacy?:** (`AgentStreamOptions | ({ requestContext: RequestContext }) => AgentStreamOptions | Promise<AgentStreamOptions>`): Default options used when calling \`streamLegacy()\`.
+
+**mastra?:** (`Mastra`): Reference to the Mastra runtime instance (injected automatically).
+
+**scorers?:** (`MastraScorers | ({ requestContext: RequestContext }) => MastraScorers | Promise<MastraScorers>`): Scoring configuration for runtime evaluation and telemetry. Can be static or dynamically provided.
+
+**memory?:** (`MastraMemory | ({ requestContext: RequestContext }) => MastraMemory | Promise<MastraMemory>`): Memory module used for storing and retrieving stateful context.
+
+**voice?:** (`CompositeVoice`): Voice settings for speech input and output.
+
+**inputProcessors?:** (`(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>`): Input processors that can modify or validate messages before they are processed by the agent. Can be individual Processor objects or workflows created with \`createWorkflow()\` using ProcessorStepSchema.
+
+**outputProcessors?:** (`(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>`): Output processors that can modify or validate messages from the agent before they are sent to the client. Can be individual Processor objects or workflows.
+
+**maxProcessorRetries?:** (`number`): Maximum number of times a processor can request retrying the LLM step.
+
+**requestContextSchema?:** (`z.ZodType<any>`): Zod schema for validating request context values. When provided, the context is validated at the start of generate() or stream(), throwing a MastraError if validation fails.
+
+## Returns
+
+**agent:** (`Agent<TAgentId, TTools>`): A new Agent instance with the specified configuration.
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)

package/.docs/reference/agents/generate.md

@@ -0,0 +1,186 @@
+# Agent.generate()
+
+The `.generate()` method enables non-streaming response generation from an agent with enhanced capabilities. It accepts messages and optional generation options.
+
+## Usage example
+
+```typescript
+// Basic usage
+const result = await agent.generate('message for agent')
+
+// With model settings (e.g., limiting output tokens)
+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 for conversation persistence
+const memoryResult = await agent.generate('Remember my favorite color is blue', {
+  memory: {
+    thread: 'user-123-thread',
+    resource: 'user-123',
+  },
+})
+
+// Accessing response headers
+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.
+
+## Parameters
+
+**messages:** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): The messages to send to the agent. Can be a single string, array of strings, or structured message objects.
+
+**options?:** (`AgentExecutionOptions<Output, Format>`): Optional configuration for the generation process.
+
+### Options
+
+**maxSteps?:** (`number`): Maximum number of steps to run during execution.
+
+**stopWhen?:** (`LoopOptions['stopWhen']`): Conditions for stopping execution (e.g., step count, token limit).
+
+**onIterationComplete?:** (`(context: IterationCompleteContext) => { continue?: boolean; feedback?: string } | void | Promise<{ continue?: boolean; feedback?: string } | void>`): context.iteration:numberCurrent iteration number (1-based).context.maxIterations:number | undefinedMaximum iterations allowed (if set).context.text:stringThe text response from this iteration.context.isFinal:booleanWhether this is the final iteration.context.finishReason:stringReason why this iteration finished (e.g., 'stop', 'length', 'tool-calls').context.toolCalls:ToolCall\[]Tool calls made in this iteration.context.messages:MastraDBMessage\[]All messages accumulated so far.return.continue?:booleanSet to false to stop execution early.return.feedback?:stringFeedback message to guide the agent's next iteration.
+
+**isTaskComplete?:** (`IsTaskCompleteConfig`): scorers:MastraScorer\[]Array of scorers that evaluate task completion. Each scorer returns 0 (failed) or 1 (passed).strategy?:'all' | 'any'Strategy for combining scorer results. 'all' requires all scorers to pass, 'any' requires at least one.onComplete?:(result: IsTaskCompleteRunResult) => void | Promise\<void>Callback called when the task completion check finishes. Receives the result with individual scorer scores.parallel?:booleanWhether to run scorers in parallel.timeout?:numberMaximum time in milliseconds to wait for all scorers to complete.
+
+**delegation?:** (`DelegationConfig`): onDelegationStart?:(context: DelegationStartContext) => DelegationStartResult | void | Promise\<DelegationStartResult | void>Called before delegating to a subagent. Use this to modify the delegation parameters or reject the delegation entirely.onDelegationComplete?:(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>Called after a subagent delegation completes. The context includes a \`bail()\` method to stop further execution, and you can return \`{ feedback }\` to guide the supervisor's next action. Feedback is saved to supervisor memory as an assistant message.messageFilter?:(context: MessageFilterContext) => MastraDBMessage\[] | Promise\<MastraDBMessage\[]>Callback function called before delegating to a subagent. Use this to filter the messages that are passed to the subagent.
+
+**scorers?:** (`MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>`): scorer:stringName of the scorer to use.sampling?:ScoringSamplingConfigSampling configuration for the scorer.type:'none' | 'ratio'Type of sampling strategy. Use 'none' to disable sampling or 'ratio' for percentage-based sampling.rate?:numberSampling rate (0-1). Required when type is 'ratio'.
+
+**returnScorerData?:** (`boolean`): Whether to return detailed scoring data in the response.
+
+**onChunk?:** (`(chunk: ChunkType) => Promise<void> | void`): Callback function called for each chunk during generation.
+
+**onError?:** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during generation.
+
+**onAbort?:** (`(event: any) => Promise<void> | void`): Callback function called when the generation is aborted.
+
+**activeTools?:** (`Array<keyof ToolSet> | undefined`): Array of tool names that should be active during execution. If undefined, all available tools are active.
+
+**abortSignal?:** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.
+
+**prepareStep?:** (`PrepareStepFunction`): Callback function called before each step of multi-step execution.
+
+**requireToolApproval?:** (`boolean`): When true, all tool calls require explicit approval before execution. The generate() method will return with \`finishReason: 'suspended'\` and include a \`suspendPayload\` with tool call details (\`toolCallId\`, \`toolName\`, \`args\`). Use \`approveToolCallGenerate()\` or \`declineToolCallGenerate()\` to proceed. See \[Agent Approval]\(/docs/agents/agent-approval#tool-approval-with-generate) for details.
+
+**autoResumeSuspendedTools?:** (`boolean`): When true, automatically resumes suspended tools when the user sends a new message on the same thread. The agent extracts \`resumeData\` from the user's message based on the tool's \`resumeSchema\`. Requires memory to be configured.
+
+**toolCallConcurrency?:** (`number`): Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.
+
+**context?:** (`ModelMessage[]`): Additional context messages to provide to the agent.
+
+**structuredOutput?:** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): schema:z.ZodSchema\<S>Zod schema defining the expected output structure.model?:MastraLanguageModelLanguage model to use for structured output generation. If provided, enables the agent to respond in multi step with tool calls, text, and structured outputerrorStrategy?:'strict' | 'warn' | 'fallback'Strategy for handling schema validation errors. 'strict' throws errors, 'warn' logs warnings, 'fallback' uses fallback values.fallbackValue?:\<S extends ZodTypeAny>Fallback value to use when schema validation fails and errorStrategy is 'fallback'.instructions?:stringAdditional instructions for the structured output model.jsonPromptInjection?:booleanInjects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs.logger?:IMastraLoggerOptional logger instance for structured logging during output generation.providerOptions?:ProviderOptionsProvider-specific options passed to the internal structuring agent. Use this to control model behavior like reasoning effort for thinking models (e.g., \`{ openai: { reasoningEffort: 'low' } }\`).
+
+**outputProcessors?:** (`OutputProcessorOrWorkflow[]`): Output processors to use for this execution (overrides agent's default).
+
+**maxProcessorRetries?:** (`number`): Maximum number of times processors can trigger a retry for this generation. Overrides agent's default maxProcessorRetries.
+
+**inputProcessors?:** (`InputProcessorOrWorkflow[]`): Input processors to use for this execution (overrides agent's default).
+
+**instructions?:** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): Custom instructions that override the agent's default instructions for this execution. Can be a single string, message object, or array of either.
+
+**system?:** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): Custom system message(s) to include in the prompt. Can be a single string, message object, or array of either. System messages provide additional context or behavior instructions that supplement the agent's main instructions.
+
+**output?:** (`Zod schema | JsonSchema7`): \*\*Deprecated.\*\* Use structuredOutput without a model to achieve the same thing. Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.
+
+**memory?:** (`object`): thread:string | { id: string; metadata?: Record\<string, any>, title?: string }Thread identifier for conversation continuity. Can be a string ID or an object with ID and optional metadata/title.resource:stringResource identifier for organizing conversations by user, session, or context.options?:MemoryConfigAdditional memory configuration options including lastMessages, readOnly, semanticRecall, and workingMemory.
+
+**onFinish?:** (`LoopConfig['onFinish']`): Callback fired when generation completes.
+
+**onStepFinish?:** (`LoopConfig['onStepFinish']`): Callback fired after each generation step.
+
+**telemetry?:** (`TelemetrySettings`): isEnabled?:booleanWhether telemetry collection is enabled.recordInputs?:booleanWhether to record input data in telemetry.recordOutputs?:booleanWhether to record output data in telemetry.functionId?:stringIdentifier for the function being executed.
+
+**modelSettings?:** (`CallSettings`): temperature?:numberControls randomness in generation (0-2). Higher values make output more random.maxOutputTokens?:numberMaximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.maxRetries?:numberMaximum number of retry attempts for failed requests.topP?:numberNucleus sampling parameter (0-1). Controls diversity of generated text.topK?:numberTop-k sampling parameter. Limits vocabulary to k most likely tokens.presencePenalty?:numberPenalty for token presence (-2 to 2). Reduces repetition.frequencyPenalty?:numberPenalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.stopSequences?:string\[]Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
+
+**toolChoice?:** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): 'auto':stringLet the model decide when to use tools (default).'none':stringDisable tool usage entirely.'required':stringForce the model to use at least one tool.{ type: 'tool'; toolName: string }:objectForce the model to use a specific tool.
+
+**toolsets?:** (`ToolsetsInput`): Additional tool sets that can be used for this execution.
+
+**clientTools?:** (`ToolsInput`): Client-side tools available during execution.
+
+**savePerStep?:** (`boolean`): Save messages incrementally after each generation step completes (default: false).
+
+**providerOptions?:** (`Record<string, Record<string, JSONValue>>`): openai?:Record\<string, JSONValue>OpenAI-specific options like reasoningEffort, responseFormat, etc.anthropic?:Record\<string, JSONValue>Anthropic-specific options like maxTokens, etc.google?:Record\<string, JSONValue>Google-specific options.\[providerName]?:Record\<string, JSONValue>Any provider-specific options.
+
+**runId?:** (`string`): Unique identifier for this execution run.
+
+**requestContext?:** (`RequestContext`): Request Context containing dynamic configuration and state.
+
+**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+**includeRawChunks?:** (`boolean`): Whether to include raw chunks in the stream output. Not available on all model providers.
+
+## Returns
+
+**result:** (`Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>`): Returns the full output of the generation process including text, object (if structured output), tool calls, tool results, usage statistics, and step information.
+
+**text:** (`string`): The generated text response from the agent.
+
+**object?:** (`Output | undefined`): The structured output object if structuredOutput was provided, validated against the schema.
+
+**toolCalls:** (`ToolCall[]`): Array of tool calls made during generation.
+
+**toolResults:** (`ToolResult[]`): Array of results from tool executions.
+
+**usage:** (`TokenUsage`): Token usage statistics for the generation.
+
+**steps:** (`Step[]`): Array of execution steps, useful for debugging multi-step generations.
+
+**finishReason:** (`string`): The reason generation finished. Values include 'stop' (normal completion), 'tool-calls' (ended with tool calls), 'suspended' (waiting for tool approval), or 'error' (error occurred).
+
+**response:** (`object`): id?:stringResponse ID from the model provider.timestamp?:DateTimestamp when the response was generated.modelId?:stringModel identifier used for this response.headers?:Record\<string, string>HTTP response headers from the model provider. Contains rate limit information (e.g., \`anthropic-ratelimit-requests-remaining\`, \`x-ratelimit-remaining-tokens\`) and other provider-specific metadata.messages?:ResponseMessage\[]Response messages in model format.uiMessages?:UIMessage\[]Response messages in UI format, includes any metadata added by output processors.
+
+**request?:** (`object`): body?:unknownThe request body sent to the model provider.
+
+**warnings?:** (`LanguageModelWarning[]`): Any warnings from the model provider during generation.
+
+**providerMetadata?:** (`Record<string, unknown>`): Provider-specific metadata returned with the response.
+
+**reasoning?:** (`ReasoningChunk[]`): Reasoning details from models that support reasoning (e.g., OpenAI o1 series).
+
+**reasoningText?:** (`string`): Combined reasoning text from reasoning models.
+
+**sources?:** (`SourceChunk[]`): Sources referenced by the model during generation.
+
+**files?:** (`FileChunk[]`): Files generated by the model.
+
+**suspendPayload?:** (`object`): toolCallId:stringUnique identifier for the pending tool call.toolName:stringName of the tool that requires approval.args:Record\<string, any>Arguments that will be passed to the tool.
+
+**runId?:** (`string`): Unique identifier for this execution run. Required when calling \`approveToolCallGenerate()\` or \`declineToolCallGenerate()\` to resume a suspended execution.
+
+**traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.
+
+**messages:** (`MastraDBMessage[]`): All messages from this execution including input, memory history, and response.
+
+**rememberedMessages:** (`MastraDBMessage[]`): Only messages loaded from memory (conversation history).
+
+**error?:** (`Error`): Error object if the generation failed.
+
+**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)