@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

package/.docs/raw/agents/networks.mdx

@@ -1,6 +1,10 @@
 ---
 title: "Agent Networks | Agents"
 description: Learn how to coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
+packages:
+  - "@mastra/core"
+  - "@mastra/libsql"
+  - "@mastra/memory"
 ---
 
 # Agent Networks
@@ -23,7 +27,7 @@ Mastra agent networks operate using these principles:
 
 An agent network is built around a top-level routing agent that delegates tasks to agents, workflows, and tools defined in its configuration. Memory is configured on the routing agent using the `memory` option, and `instructions` define the agent's routing behavior.
 
-```typescript {22-23,26,29} title="src/mastra/agents/routing-agent.ts" showLineNumbers copy
+```typescript {22-23,26,29} title="src/mastra/agents/routing-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -71,25 +75,23 @@ When configuring a Mastra agent network, each primitive (agent, workflow, or too
 
 Each agent in a network should include a clear `description` that explains what the agent does.
 
-```typescript title="src/mastra/agents/research-agent.ts" showLineNumbers
+```typescript title="src/mastra/agents/research-agent.ts"
 export const researchAgent = new Agent({
   id: "research-agent",
   name: "Research Agent",
   description: `This agent gathers concise research insights in bullet-point form.
     It's designed to extract key facts without generating full
     responses or narrative content.`,
-  // ...
 });
 ```
 
-```typescript title="src/mastra/agents/writing-agent.ts" showLineNumbers
+```typescript title="src/mastra/agents/writing-agent.ts"
 export const writingAgent = new Agent({
   id: "writing-agent",
   name: "Writing Agent",
   description: `This agent turns researched material into well-structured
     written content. It produces full-paragraph reports with no bullet points,
     suitable for use in articles, summaries, or blog posts.`,
-  // ...
 });
 ```
 
@@ -97,7 +99,7 @@ export const writingAgent = new Agent({
 
 Workflows in a network should include a `description` to explain their purpose, along with `inputSchema` and `outputSchema` to describe the expected data.
 
-```typescript title="src/mastra/workflows/city-workflow.ts" showLineNumbers
+```typescript title="src/mastra/workflows/city-workflow.ts"
 export const cityWorkflow = createWorkflow({
   id: "city-workflow",
   description: `This workflow handles city-specific research tasks.
@@ -110,7 +112,6 @@ export const cityWorkflow = createWorkflow({
   outputSchema: z.object({
     text: z.string(),
   }),
-  //...
 });
 ```
 
@@ -118,7 +119,7 @@ export const cityWorkflow = createWorkflow({
 
 Tools in a network should include a `description` to explain their purpose, along with `inputSchema` and `outputSchema` to describe the expected data.
 
-```typescript title="src/mastra/tools/weather-tool.ts" showLineNumbers
+```typescript title="src/mastra/tools/weather-tool.ts"
 export const weatherTool = createTool({
   id: "weather-tool",
   description: ` Retrieves current weather information using the wttr.in API.
@@ -131,7 +132,6 @@ export const weatherTool = createTool({
   outputSchema: z.object({
     weather: z.string(),
   }),
-  // ...
 });
 ```
 
@@ -143,7 +143,7 @@ Call a Mastra agent network using `.network()` with a user message. The method r
 
 In this example, the network interprets the message and would route the request to both the `researchAgent` and `writingAgent` to generate a complete response.
 
-```typescript showLineNumbers copy
+```typescript
 const result = await routingAgent.network(
   "Tell me three cool ways to use Mastra",
 );
@@ -179,7 +179,7 @@ network-execution-event-step-finish
 
 In this example, the routing agent recognizes the city name in the message and runs the `cityWorkflow`. The workflow defines steps that call the `researchAgent` to gather facts, then the `writingAgent` to generate the final text.
 
-```typescript showLineNumbers copy
+```typescript
 const result = await routingAgent.network(
   "Tell me some historical facts about London",
 );
@@ -212,7 +212,7 @@ network-execution-event-step-finish
 
 In this example, the routing agent skips the `researchAgent`, `writingAgent`, and `cityWorkflow`, and calls the `weatherTool` directly to complete the task.
 
-```typescript showLineNumbers copy
+```typescript
 const result = await routingAgent.network("What's the weather in London?");
 
 for await (const chunk of result) {
@@ -235,9 +235,65 @@ tool-execution-end
 network-execution-event-step-finish
 ```
 
+## Structured output
+
+When you need typed, validated results from a network, use the `structuredOutput` option. After the network completes its task, it generates a structured response matching your schema.
+
+```typescript
+import { z } from "zod";
+
+const resultSchema = z.object({
+  summary: z.string().describe("A brief summary of the findings"),
+  recommendations: z.array(z.string()).describe("List of recommendations"),
+  confidence: z.number().min(0).max(1).describe("Confidence score"),
+});
+
+const stream = await routingAgent.network("Research AI trends", {
+  structuredOutput: {
+    schema: resultSchema,
+  },
+});
+
+// Consume the stream
+for await (const chunk of stream) {
+  if (chunk.type === "network-object") {
+    // Partial object during generation
+    console.log("Partial:", chunk.payload.object);
+  }
+  if (chunk.type === "network-object-result") {
+    // Final structured object
+    console.log("Final:", chunk.payload.object);
+  }
+}
+
+// Get the typed result
+const result = await stream.object;
+console.log(result?.summary);
+console.log(result?.recommendations);
+console.log(result?.confidence);
+```
+
+### Streaming partial objects
+
+For real-time updates during structured output generation, use `objectStream`:
+
+```typescript
+const stream = await routingAgent.network("Analyze market data", {
+  structuredOutput: { schema: resultSchema },
+});
+
+// Stream partial objects as they're generated
+for await (const partial of stream.objectStream) {
+  console.log("Building result:", partial);
+}
+
+// Get the final typed result
+const final = await stream.object;
+```
+
 ## Related
 
 - [Agent Memory](./agent-memory)
 - [Workflows Overview](../workflows/overview)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)
 - [Supervisor example](https://github.com/mastra-ai/mastra/tree/main/examples/supervisor-agent)

package/.docs/raw/agents/overview.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Using Agents | Agents"
 description: Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
+packages:
+  - "@mastra/core"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -39,7 +41,7 @@ npm install @mastra/core@beta
 
 Mastra's model router auto-detects environment variables for your chosen provider. For OpenAI, set `OPENAI_API_KEY`:
 
-```bash title=".env" copy
+```bash title=".env"
 OPENAI_API_KEY=<your-api-key>
 ```
 
@@ -55,7 +57,7 @@ Mastra supports more than 600 models. Choose from the [full list](/models/v1).
 
 Create an agent by instantiating the `Agent` class with system `instructions` and a `model`:
 
-```typescript title="src/mastra/agents/test-agent.ts" copy
+```typescript title="src/mastra/agents/test-agent.ts"
 import { Agent } from "@mastra/core/agent";
 
 export const testAgent = new Agent({
@@ -77,7 +79,7 @@ They are system-level prompts that establish the agent's core identity and exper
 
 Instructions can be provided in multiple formats for greater flexibility. The examples below illustrate the supported shapes:
 
-```typescript copy
+```typescript
 // String (most common)
 instructions: "You are a helpful assistant.";
 
@@ -99,7 +101,7 @@ instructions: [
 
 Each model provider also enables a few different options, including prompt caching and configuring reasoning. We provide a `providerOptions` flag to manage these. You can set `providerOptions` on the instruction level to set different caching strategy per system instruction/prompt.
 
-```typescript copy
+```typescript
 // With provider-specific options (e.g., caching, reasoning)
 instructions: {
   role: "system",
@@ -112,18 +114,21 @@ instructions: {
 }
 ```
 
-> See the [Agent reference doc](/reference/v1/agents/agent) for more information.
+:::info
+
+Visit [Agent reference](/reference/v1/agents/agent) for more information.
+
+:::
 
 ### Registering an agent
 
 Register your agent in the Mastra instance to make it available throughout your application. Once registered, it can be called from workflows, tools, or other agents, and has access to shared resources such as memory, logging, and observability features:
 
-```typescript {6} showLineNumbers title="src/mastra/index.ts" copy
+```typescript {5} title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { testAgent } from "./agents/test-agent";
 
 export const mastra = new Mastra({
-  // ...
   agents: { testAgent },
 });
 ```
@@ -132,7 +137,7 @@ export const mastra = new Mastra({
 
 You can call agents from workflow steps, tools, the Mastra Client, or the command line. Get a reference by calling `.getAgent()` on your `mastra` or `mastraClient` instance, depending on your setup:
 
-```typescript showLineNumbers copy
+```typescript
 const testAgent = mastra.getAgent("testAgent");
 ```
 
@@ -152,7 +157,7 @@ Pass a single string for simple prompts, an array of strings when providing mult
 
 (The `role` defines the speaker for each message. Typical roles are `user` for human input, `assistant` for agent responses, and `system` for instructions.)
 
-```typescript showLineNumbers copy
+```typescript
 const response = await testAgent.generate([
   { role: "user", content: "Help me organize my day" },
   { role: "user", content: "My day starts at 9am and finishes at 5.30pm" },
@@ -172,7 +177,7 @@ Pass a single string for simple prompts, an array of strings when providing mult
 
 (The `role` defines the speaker for each message. Typical roles are `user` for human input, `assistant` for agent responses, and `system` for instructions.)
 
-```typescript showLineNumbers copy
+```typescript
 const stream = await testAgent.stream([
   { role: "user", content: "Help me organize my day" },
   { role: "user", content: "My day starts at 9am and finishes at 5.30pm" },
@@ -188,12 +193,12 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
-### Completion using `onFinish()`
+<h3 id="completion-using-onfinish">Completion using `onFinish()`</h3>
 
 When streaming responses, the `onFinish()` callback runs after the LLM finishes generating its response and all tool executions are complete.
 It provides the final `text`, execution `steps`, `finishReason`, token `usage` statistics, and other metadata useful for monitoring or logging.
 
-```typescript showLineNumbers copy
+```typescript
 const stream = await testAgent.stream("Help me organize my day", {
   onFinish: ({ steps, text, finishReason, usage }) => {
     console.log({ steps, text, finishReason, usage });
@@ -208,19 +213,27 @@ for await (const chunk of stream.textStream) {
   </TabItem>
 </Tabs>
 
-> See [.generate()](/reference/v1/agents/generate) or [.stream()](/reference/v1/streaming/agents/stream) for more information.
+:::info
+
+Visit [.generate()](/reference/v1/agents/generate) or [.stream()](/reference/v1/streaming/agents/stream) for more information.
+
+:::
 
 ## Structured output
 
 Agents can return structured, type-safe data using Zod or JSON Schema. The parsed result is available on `response.object`.
 
-> See [Structured Output](/docs/v1/agents/structured-output) for more information.
+:::info
+
+Visit [Structured Output](/docs/v1/agents/structured-output) for more information.
+
+:::
 
 ## Analyzing images
 
 Agents can analyze and describe images by processing both the visual content and any text within them. To enable image analysis, pass an object with `type: 'image'` and the image URL in the `content` array. You can combine image content with text prompts to guide the agent's analysis.
 
-```typescript showLineNumbers copy
+```typescript
 const response = await testAgent.generate([
   {
     role: "user",
@@ -241,12 +254,11 @@ const response = await testAgent.generate([
 console.log(response.text);
 ```
 
-
 ## Using `maxSteps`
 
 The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make. Each step includes generating a response, executing any tool calls, and processing the result. Limiting steps helps prevent infinite loops, reduce latency, and control token usage for agents that use tools. The default is 1, but can be increased:
 
-```typescript showLineNumbers copy
+```typescript
 const response = await testAgent.generate("Help me organize my day", {
   maxSteps: 10,
 });
@@ -260,7 +272,7 @@ You can monitor the progress of multi-step operations using the `onStepFinish` c
 
 `onStepFinish` is only available when streaming or generating text without structured output.
 
-```typescript showLineNumbers copy
+```typescript
 const response = await testAgent.generate("Help me organize my day", {
   onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
     console.log({ text, toolCalls, toolResults, finishReason, usage });
@@ -272,22 +284,25 @@ const response = await testAgent.generate("Help me organize my day", {
 
 Agents can use tools to go beyond language generation, enabling structured interactions with external APIs and services. Tools allow agents to access data and perform clearly defined operations in a reliable, repeatable way.
 
-```typescript title="src/mastra/agents/test-agent.ts" showLineNumbers
+```typescript title="src/mastra/agents/test-agent.ts"
 export const testAgent = new Agent({
   id: "test-agent",
   name: "Test Agent",
-  // ...
   tools: { testTool },
 });
 ```
 
-> See [Using Tools](/docs/v1/agents/using-tools) for more information.
+:::info
+
+Visit [Using Tools](/docs/v1/agents/using-tools) for more information.
+
+:::
 
 ## Using `RequestContext`
 
 Use `RequestContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
 
-```typescript title="src/mastra/agents/test-agent.ts" showLineNumbers
+```typescript title="src/mastra/agents/test-agent.ts"
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
@@ -295,7 +310,6 @@ export type UserTier = {
 export const testAgent = new Agent({
   id: "test-agent",
   name: "Test Agent",
-  // ...
   model: ({ requestContext }) => {
     const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
@@ -306,7 +320,11 @@ export const testAgent = new Agent({
 });
 ```
 
-> See [Request Context](/docs/v1/server-db/request-context) for more information.
+:::info
+
+See [Request Context](/docs/v1/server/request-context) for more information.
+
+:::
 
 ## Testing with Studio
 
@@ -316,4 +334,4 @@ Use [Studio](/docs/v1/getting-started/studio) to test agents with different mess
 
 - [Using Tools](/docs/v1/agents/using-tools)
 - [Agent Memory](/docs/v1/agents/agent-memory)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)