@mastra/core 1.6.0 → 1.7.0-alpha.0

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

@@ -1,271 +0,0 @@
-# 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/dist/docs/references/docs-agents-using-tools.md

@@ -1,214 +0,0 @@
-# Using 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.
-
-## Creating a tool
-
-When creating tools, keep descriptions simple 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.
-
-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.
-
-```typescript
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-export const weatherTool = createTool({
-  id: "weather-tool",
-  description: "Fetches weather for a location",
-  inputSchema: z.object({
-    location: z.string(),
-  }),
-  outputSchema: z.object({
-    weather: z.string(),
-  }),
-  execute: async (inputData) => {
-    const { location } = inputData;
-
-    const response = await fetch(`https://wttr.in/${location}?format=3`);
-    const weather = await response.text();
-
-    return { weather };
-  },
-});
-```
-
-## Adding tools to an agent
-
-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.
-
-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";
-
-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.`,
-  model: "openai/gpt-5.1",
-  tools: { weatherTool },
-});
-```
-
-## Using 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.
-
-```typescript
-import { weatherTool } from "../tools/weather-tool";
-import { activitiesTool } from "../tools/activities-tool";
-
-export const weatherAgent = new Agent({
-  id: "weather-agent",
-  name: "Weather Agent",
-  tools: { weatherTool, activitiesTool },
-});
-```
-
-## Using agents as tools
-
-Agents can be added to other agents through the `agents` configuration. When you add a subagent, Mastra automatically converts it to a tool that the parent agent can call. The generated tool is named `agent-<agentName>`.
-
-```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`,
-  model: "openai/gpt-5.1",
-  agents: {
-    subAgent,
-  },
-});
-
-const subAgent = new Agent({
-  id: "sub-agent",
-  name: "Sub Agent",
-  description: "Take care in writing a good description here",
-  instructions: `Instructions`,
-  model: "openai/gpt-5.1",
-})
-```
-
-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 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`.
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-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.`,
-  model: "openai/gpt-5.1",
-  tools: {
-    weatherTool,
-  },
-  workflows: {
-    researchWorkflow,
-  },
-});
-```
-
-The workflow should include a `description` to help the agent understand when to use it:
-
-```typescript
-import { createWorkflow } from "@mastra/core/workflows";
-import { z } from "zod";
-
-export const researchWorkflow = createWorkflow({
-  id: "research-workflow",
-  description: "Gathers information on a topic and compiles a summary report.",
-  // Rest of the workflow...
-})
-  .commit();
-```
-
-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:
-
-```typescript
-{
-  result: { summary: "...", sources: ["..."] },
-  runId: "abc-123"
-}
-```
-
-See the [`toolName` docs](#subagents-and-workflows-as-tools) to learn more about the tool naming scheme.
-
-## Controlling `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",
-  // ...
-});
-
-// Using the variable name as the key
-tools: { weatherTool }
-// Stream returns: toolName: "weatherTool"
-
-// Using the tool's id as the key
-tools: { [weatherTool.id]: weatherTool }
-// Stream returns: toolName: "weather-tool"
-
-// Using a custom key
-tools: { "my-custom-name": weatherTool }
-// Stream returns: toolName: "my-custom-name"
-```
-
-This lets you specify how tools are identified in the stream. If you want the `toolName` to match the tool's `id`, use the tool's `id` as the object key.
-
-### Subagents and workflows as tools
-
-Subagents and workflows follow the same pattern. They are converted to tools with a prefix followed by your object key:
-
-| Property    | Prefix      | Example key | `toolName`          |
-| ----------- | ----------- | ----------- | ------------------- |
-| `agents`    | `agent-`    | `weather`   | `agent-weather`     |
-| `workflows` | `workflow-` | `research`  | `workflow-research` |
-
-```typescript
-const orchestrator = new Agent({
-  agents: {
-    weather: weatherAgent,  // toolName: "agent-weather"
-  },
-  workflows: {
-    research: researchWorkflow,  // toolName: "workflow-research"
-  },
-});
-```
-
-Note that for subagents, you'll see two different identifiers in stream responses:
-
-- `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)
-- [Request Context](https://mastra.ai/docs/server/request-context)