@mastra/mcp-docs-server 0.13.30 → 0.13.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/.docs/organized/changelogs/%40internal%2Fchangeset-cli.md +4 -0
  2. package/.docs/organized/changelogs/%40internal%2Fstorage-test-utils.md +15 -15
  3. package/.docs/organized/changelogs/%40internal%2Ftypes-builder.md +4 -0
  4. package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +22 -22
  5. package/.docs/organized/changelogs/%40mastra%2Fai-sdk.md +48 -6
  6. package/.docs/organized/changelogs/%40mastra%2Fastra.md +16 -16
  7. package/.docs/organized/changelogs/%40mastra%2Fchroma.md +16 -16
  8. package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +16 -16
  9. package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +28 -28
  10. package/.docs/organized/changelogs/%40mastra%2Fcloud.md +16 -16
  11. package/.docs/organized/changelogs/%40mastra%2Fcloudflare-d1.md +16 -16
  12. package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +16 -16
  13. package/.docs/organized/changelogs/%40mastra%2Fcore.md +120 -120
  14. package/.docs/organized/changelogs/%40mastra%2Fcouchbase.md +17 -17
  15. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +37 -37
  16. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloudflare.md +41 -41
  17. package/.docs/organized/changelogs/%40mastra%2Fdeployer-netlify.md +41 -41
  18. package/.docs/organized/changelogs/%40mastra%2Fdeployer-vercel.md +41 -41
  19. package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +65 -65
  20. package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md +16 -16
  21. package/.docs/organized/changelogs/%40mastra%2Fevals.md +33 -33
  22. package/.docs/organized/changelogs/%40mastra%2Flance.md +16 -16
  23. package/.docs/organized/changelogs/%40mastra%2Flibsql.md +16 -16
  24. package/.docs/organized/changelogs/%40mastra%2Floggers.md +17 -17
  25. package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +23 -23
  26. package/.docs/organized/changelogs/%40mastra%2Fmcp-registry-registry.md +16 -16
  27. package/.docs/organized/changelogs/%40mastra%2Fmcp.md +16 -16
  28. package/.docs/organized/changelogs/%40mastra%2Fmemory.md +30 -30
  29. package/.docs/organized/changelogs/%40mastra%2Fmongodb.md +16 -16
  30. package/.docs/organized/changelogs/%40mastra%2Fmssql.md +16 -16
  31. package/.docs/organized/changelogs/%40mastra%2Fopensearch.md +16 -16
  32. package/.docs/organized/changelogs/%40mastra%2Fpg.md +41 -41
  33. package/.docs/organized/changelogs/%40mastra%2Fpinecone.md +16 -16
  34. package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +71 -71
  35. package/.docs/organized/changelogs/%40mastra%2Fqdrant.md +16 -16
  36. package/.docs/organized/changelogs/%40mastra%2Frag.md +16 -16
  37. package/.docs/organized/changelogs/%40mastra%2Freact.md +41 -0
  38. package/.docs/organized/changelogs/%40mastra%2Fs3vectors.md +15 -0
  39. package/.docs/organized/changelogs/%40mastra%2Fserver.md +37 -37
  40. package/.docs/organized/changelogs/%40mastra%2Fturbopuffer.md +16 -16
  41. package/.docs/organized/changelogs/%40mastra%2Fupstash.md +19 -19
  42. package/.docs/organized/changelogs/%40mastra%2Fvectorize.md +16 -16
  43. package/.docs/organized/changelogs/%40mastra%2Fvoice-azure.md +17 -17
  44. package/.docs/organized/changelogs/%40mastra%2Fvoice-cloudflare.md +16 -16
  45. package/.docs/organized/changelogs/%40mastra%2Fvoice-deepgram.md +16 -16
  46. package/.docs/organized/changelogs/%40mastra%2Fvoice-elevenlabs.md +16 -16
  47. package/.docs/organized/changelogs/%40mastra%2Fvoice-gladia.md +17 -17
  48. package/.docs/organized/changelogs/%40mastra%2Fvoice-google-gemini-live.md +15 -0
  49. package/.docs/organized/changelogs/%40mastra%2Fvoice-google.md +16 -16
  50. package/.docs/organized/changelogs/%40mastra%2Fvoice-murf.md +16 -16
  51. package/.docs/organized/changelogs/%40mastra%2Fvoice-openai-realtime.md +16 -16
  52. package/.docs/organized/changelogs/%40mastra%2Fvoice-openai.md +17 -17
  53. package/.docs/organized/changelogs/%40mastra%2Fvoice-playai.md +16 -16
  54. package/.docs/organized/changelogs/%40mastra%2Fvoice-sarvam.md +16 -16
  55. package/.docs/organized/changelogs/%40mastra%2Fvoice-speechify.md +16 -16
  56. package/.docs/organized/changelogs/create-mastra.md +41 -41
  57. package/.docs/organized/changelogs/mastra.md +73 -73
  58. package/.docs/organized/code-examples/heads-up-game.md +5 -5
  59. package/.docs/raw/agents/agent-memory.mdx +1 -1
  60. package/.docs/raw/agents/networks.mdx +0 -2
  61. package/.docs/raw/agents/overview.mdx +71 -38
  62. package/.docs/raw/agents/using-tools.mdx +1 -1
  63. package/.docs/raw/frameworks/agentic-uis/ai-sdk.mdx +284 -266
  64. package/.docs/raw/reference/agents/generate.mdx +13 -5
  65. package/.docs/raw/reference/agents/getDefaultGenerateOptions.mdx +1 -1
  66. package/.docs/raw/reference/agents/getDefaultStreamOptions.mdx +2 -2
  67. package/.docs/raw/reference/agents/getInstructions.mdx +1 -1
  68. package/.docs/raw/reference/agents/getLLM.mdx +1 -1
  69. package/.docs/raw/reference/agents/getMemory.mdx +1 -1
  70. package/.docs/raw/reference/agents/getModel.mdx +1 -1
  71. package/.docs/raw/reference/agents/getScorers.mdx +1 -1
  72. package/.docs/raw/reference/cli/create-mastra.mdx +16 -0
  73. package/.docs/raw/reference/cli/mastra.mdx +7 -1
  74. package/.docs/raw/reference/streaming/ChunkType.mdx +1 -1
  75. package/.docs/raw/reference/streaming/agents/MastraModelOutput.mdx +1 -2
  76. package/.docs/raw/reference/streaming/agents/stream.mdx +18 -10
  77. package/.docs/raw/reference/streaming/agents/streamLegacy.mdx +2 -2
  78. package/.docs/raw/reference/tools/create-tool.mdx +1 -1
  79. package/.docs/raw/reference/tools/graph-rag-tool.mdx +2 -2
  80. package/.docs/raw/reference/tools/vector-query-tool.mdx +2 -2
  81. package/.docs/raw/reference/vectors/pg.mdx +83 -2
  82. package/.docs/raw/server-db/runtime-context.mdx +4 -2
  83. package/.docs/raw/streaming/events.mdx +108 -0
  84. package/.docs/raw/streaming/overview.mdx +41 -1
  85. package/.docs/raw/tools-mcp/overview.mdx +2 -38
  86. package/.docs/raw/workflows/overview.mdx +137 -229
  87. package/CHANGELOG.md +14 -0
  88. package/package.json +4 -4
@@ -37,7 +37,7 @@ const aiSdkResult = await agent.generate("message for agent", {
37
37
  },
38
38
  {
39
39
  name: "options",
40
- type: "AgentExecutionOptions<Output, StructuredOutput, Format>",
40
+ type: "AgentExecutionOptions<Output, Format>",
41
41
  isOptional: true,
42
42
  description: "Optional configuration for the generation process.",
43
43
  },
@@ -163,7 +163,7 @@ const aiSdkResult = await agent.generate("message for agent", {
163
163
  name: "structuredOutput",
164
164
  type: "StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>",
165
165
  isOptional: true,
166
- description: "Enables structured output generation with better developer experience. Automatically creates and uses a StructuredOutputProcessor internally.",
166
+ description: "Options to fine tune your structured output generation.",
167
167
  properties: [
168
168
  {
169
169
  parameters: [{
@@ -178,7 +178,7 @@ const aiSdkResult = await agent.generate("message for agent", {
178
178
  name: "model",
179
179
  type: "MastraLanguageModel",
180
180
  isOptional: true,
181
- description: "Language model to use for structured output generation. If not provided, uses the agent's default model."
181
+ description: "Language model to use for structured output generation. If provided, enables the agent to respond in multi step with tool calls, text, and structured output"
182
182
  }]
183
183
  },
184
184
  {
@@ -202,7 +202,15 @@ const aiSdkResult = await agent.generate("message for agent", {
202
202
  name: "instructions",
203
203
  type: "string",
204
204
  isOptional: true,
205
- description: "Additional instructions for structured output generation."
205
+ description: "Additional instructions for the structured output model."
206
+ }]
207
+ },
208
+ {
209
+ parameters: [{
210
+ name: "jsonPromptInjection",
211
+ type: "boolean",
212
+ isOptional: true,
213
+ description: "Injects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs."
206
214
  }]
207
215
  }
208
216
  ]
@@ -235,7 +243,7 @@ const aiSdkResult = await agent.generate("message for agent", {
235
243
  name: "output",
236
244
  type: "Zod schema | JsonSchema7",
237
245
  isOptional: true,
238
- description: "**Deprecated.** Use structuredOutput with maxSteps:1 to achieve the same thing. Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
246
+ description: "**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.",
239
247
  },
240
248
  {
241
249
  name: "memory",
@@ -64,4 +64,4 @@ await agent.getDefaultGenerateOptions({
64
64
  ## Related
65
65
 
66
66
  - [Agent generation](../../docs/agents/overview.mdx#generate)
67
- - [Agent Runtime Context](../../docs/agents/runtime-context.mdx)
67
+ - [Runtime Context](../../docs/server-db/runtime-context.mdx)
@@ -33,7 +33,7 @@ await agent.getDefaultStreamOptions();
33
33
  content={[
34
34
  {
35
35
  name: "defaultOptions",
36
- type: "AgentExecutionOptions<Output, StructuredOutput> | Promise<AgentExecutionOptions<Output, StructuredOutput>>",
36
+ type: "AgentExecutionOptions<Output> | Promise<AgentExecutionOptions<Output>>",
37
37
  description: "The default vNext streaming options configured for the agent, either as a direct object or a promise that resolves to the options.",
38
38
  },
39
39
  ]}
@@ -64,4 +64,4 @@ await agent.getDefaultStreamOptions({
64
64
  ## Related
65
65
 
66
66
  - [Streaming with agents](../../docs/streaming/overview.mdx#streaming-with-agents)
67
- - [Agent Runtime Context](../../docs/agents/runtime-context.mdx)
67
+ - [Runtime Context](../../docs/server-db/runtime-context.mdx)
@@ -64,4 +64,4 @@ await agent.getInstructions({
64
64
  ## Related
65
65
 
66
66
  - [Agents overview](../../docs/agents/overview.mdx)
67
- - [Agent Runtime Context](../../docs/agents/runtime-context.mdx)
67
+ - [Runtime Context](../../docs/server-db/runtime-context.mdx)
@@ -71,4 +71,4 @@ await agent.getLLM({
71
71
  ## Related
72
72
 
73
73
  - [Agents overview](../../docs/agents/overview.mdx)
74
- - [Agent Runtime Context](../../docs/agents/runtime-context.mdx)
74
+ - [Runtime Context](../../docs/server-db/runtime-context.mdx)
@@ -64,4 +64,4 @@ await agent.getMemory({
64
64
  ## Related
65
65
 
66
66
  - [Agent memory](../../docs/agents/agent-memory.mdx)
67
- - [Agent Runtime Context](../../docs/agents/runtime-context.mdx)
67
+ - [Runtime Context](../../docs/server-db/runtime-context.mdx)
@@ -64,4 +64,4 @@ await agent.getModel({
64
64
  ## Related
65
65
 
66
66
  - [Agents overview](../../docs/agents/overview.mdx)
67
- - [Agent Runtime Context](../../docs/agents/runtime-context.mdx)
67
+ - [Runtime Context](../../docs/server-db/runtime-context.mdx)
@@ -64,4 +64,4 @@ await agent.getScorers({
64
64
  ## Related
65
65
 
66
66
  - [Agents overview](../../docs/agents/overview.mdx)
67
- - [Agent Runtime Context](../../docs/agents/runtime-context.mdx)
67
+ - [Runtime Context](../../docs/server-db/runtime-context.mdx)
@@ -159,3 +159,19 @@ Instead of an interactive prompt you can also define these CLI flags.
159
159
  },
160
160
  ]}
161
161
  />
162
+
163
+ ## Telemetry
164
+
165
+ By default, Mastra collects anonymous information about your project like your OS, Mastra version or Node.js version. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/cli/src/analytics/index.ts) to check what's collected.
166
+
167
+ You can opt out of the CLI analytics by setting an environment variable:
168
+
169
+ ```bash copy
170
+ MASTRA_TELEMETRY_DISABLED=1
171
+ ```
172
+
173
+ You can also set this while using other `mastra` commands:
174
+
175
+ ```bash copy
176
+ MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@latest
177
+ ```
@@ -203,9 +203,15 @@ Configure your code editor with Mastra's MCP server. Choose from: `"cursor" | "c
203
203
 
204
204
  The path to your Mastra folder. Defaults to `src/mastra`.
205
205
 
206
+ ### `--debug`
207
+
208
+ **Available in:** `dev`, `build`
209
+
210
+ Enable verbose logging for Mastra's internals. Defaults to `false`.
211
+
206
212
  ### `--env`
207
213
 
208
- **Available in:** `dev`, `build`, `start`
214
+ **Available in:** `dev`, `start`
209
215
 
210
216
  Custom environment variables file to include. By default, includes `.env.development`, `.env.local`, and `.env`.
211
217
 
@@ -849,6 +849,6 @@ for await (const chunk of stream.fullStream) {
849
849
 
850
850
  ## Related Types
851
851
 
852
- - [.stream()](./stream.mdx) - Method that returns streams emitting these chunks
852
+ - [.stream()](./agents/stream.mdx) - Method that returns streams emitting these chunks
853
853
  - [MastraModelOutput](./agents/MastraModelOutput.mdx) - The stream object that emits these chunks
854
854
  - [workflow.streamVNext()](./workflows/streamVNext.mdx) - Method that returns streams emitting these chunks for workflows
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Reference: MastraModelOutput (Experimental) | Agents | Mastra Docs"
2
+ title: "Reference: MastraModelOutput | Agents | Mastra Docs"
3
3
  description: "Complete reference for MastraModelOutput - the stream object returned by agent.stream() with streaming and promise-based access to model outputs."
4
4
  ---
5
5
 
@@ -225,7 +225,6 @@ const stream = await agent.stream("Generate user data", {
225
225
  email: z.string()
226
226
  })
227
227
  },
228
- maxSteps: 1
229
228
  });
230
229
 
231
230
  // Stream partial objects
@@ -38,7 +38,7 @@ const aiSdkStream = await agent.stream("message for agent", {
38
38
  },
39
39
  {
40
40
  name: "options",
41
- type: "AgentExecutionOptions<Output, StructuredOutput, Format>",
41
+ type: "AgentExecutionOptions<Output, Format>",
42
42
  isOptional: true,
43
43
  description: "Optional configuration for the streaming process.",
44
44
  },
@@ -164,14 +164,14 @@ const aiSdkStream = await agent.stream("message for agent", {
164
164
  name: "structuredOutput",
165
165
  type: "StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>",
166
166
  isOptional: true,
167
- description: "Enables structured output generation with better developer experience. Automatically creates and uses a StructuredOutputProcessor internally.",
167
+ description: "Options to fine tune your structured output generation.",
168
168
  properties: [
169
169
  {
170
170
  parameters: [{
171
171
  name: "schema",
172
172
  type: "z.ZodSchema<S>",
173
173
  isOptional: false,
174
- description: "Zod schema to validate the output against."
174
+ description: "Zod schema defining the expected output structure."
175
175
  }]
176
176
  },
177
177
  {
@@ -179,7 +179,7 @@ const aiSdkStream = await agent.stream("message for agent", {
179
179
  name: "model",
180
180
  type: "MastraLanguageModel",
181
181
  isOptional: true,
182
- description: "Model to use for the internal structuring agent. If not provided, falls back to the agent's model."
182
+ description: "Language model to use for structured output generation. If provided, enables the agent to respond in multi step with tool calls, text, and structured output"
183
183
  }]
184
184
  },
185
185
  {
@@ -187,7 +187,7 @@ const aiSdkStream = await agent.stream("message for agent", {
187
187
  name: "errorStrategy",
188
188
  type: "'strict' | 'warn' | 'fallback'",
189
189
  isOptional: true,
190
- description: "Strategy when parsing or validation fails. Defaults to 'strict'."
190
+ description: "Strategy for handling schema validation errors. 'strict' throws errors, 'warn' logs warnings, 'fallback' uses fallback values."
191
191
  }]
192
192
  },
193
193
  {
@@ -195,7 +195,7 @@ const aiSdkStream = await agent.stream("message for agent", {
195
195
  name: "fallbackValue",
196
196
  type: "<S extends ZodTypeAny>",
197
197
  isOptional: true,
198
- description: "Fallback value when errorStrategy is 'fallback'."
198
+ description: "Fallback value to use when schema validation fails and errorStrategy is 'fallback'."
199
199
  }]
200
200
  },
201
201
  {
@@ -203,7 +203,15 @@ const aiSdkStream = await agent.stream("message for agent", {
203
203
  name: "instructions",
204
204
  type: "string",
205
205
  isOptional: true,
206
- description: "Custom instructions for the structuring agent."
206
+ description: "Additional instructions for the structured output model."
207
+ }]
208
+ },
209
+ {
210
+ parameters: [{
211
+ name: "jsonPromptInjection",
212
+ type: "boolean",
213
+ isOptional: true,
214
+ description: "Injects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs."
207
215
  }]
208
216
  }
209
217
  ]
@@ -238,7 +246,7 @@ const aiSdkStream = await agent.stream("message for agent", {
238
246
  type: "Zod schema | JsonSchema7",
239
247
  isOptional: true,
240
248
  description:
241
- "**Deprecated.** Use structuredOutput with maxSteps:1 to achieve the same thing. Defines the expected structure of the output. Can be a JSON Schema object or a Zod schema.",
249
+ "**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.",
242
250
  },
243
251
  {
244
252
  name: "memory",
@@ -673,12 +681,12 @@ await agent.stream("message for agent", {
673
681
  sentiment: z.enum(['positive', 'negative', 'neutral']),
674
682
  confidence: z.number(),
675
683
  }),
676
- model: openai("gpt-4o-mini"),
684
+ model: "openai/gpt-4o-mini",
677
685
  errorStrategy: 'warn',
678
686
  },
679
687
  // Output processors for streaming response validation
680
688
  outputProcessors: [
681
- new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
689
+ new ModerationProcessor({ model: "openai/gpt-4.1-nano" }),
682
690
  new BatchPartsProcessor({ maxBatchSize: 3, maxWaitTime: 100 }),
683
691
  ],
684
692
  });
@@ -511,5 +511,5 @@ const result = await agent.stream("message", {
511
511
 
512
512
  - [Migration Guide](../../../guides/migrations/vnext-to-standard-apis)
513
513
  - [New .stream() method](./stream.mdx)
514
- - [Generating responses](../../docs/agents/overview.mdx#generating-responses)
515
- - [Streaming responses](../../docs/agents/overview.mdx#streaming-responses)
514
+ - [Generating responses](../../../docs/agents/overview.mdx#generating-responses)
515
+ - [Streaming responses](../../../docs/agents/overview.mdx#streaming-responses)
@@ -126,5 +126,5 @@ The `createTool()` function returns a `Tool` object.
126
126
 
127
127
  - [Tools Overview](/docs/tools-mcp/overview.mdx)
128
128
  - [Using Tools with Agents](/docs/agents/using-tools-and-mcp.mdx)
129
- - [Tool Runtime Context](/docs/tools-mcp/runtime-context.mdx)
129
+ - [Tool Runtime Context](/docs/tools-mcp/overview.mdx#using-runtimecontext)
130
130
  - [Advanced Tool Usage](/docs/tools-mcp/advanced-usage.mdx)
@@ -253,8 +253,8 @@ const response = await agent.generate(
253
253
 
254
254
  For more information on runtime context, please see:
255
255
 
256
- - [Agent Runtime Context](../../docs/agents/runtime-context.mdx)
257
- - [Tool Runtime Context](../../docs/tools-mcp/runtime-context.mdx)
256
+ - [Agent Runtime Context](../../docs/server-db/runtime-context.mdx)
257
+ - [Tool Runtime Context](../../docs/tools-mcp/overview.mdx#using-runtimecontext)
258
258
 
259
259
  ## Related
260
260
 
@@ -558,8 +558,8 @@ const response = await agent.generate(
558
558
 
559
559
  For more information on runtime context, please see:
560
560
 
561
- - [Agent Runtime Context](../../docs/agents/runtime-context.mdx)
562
- - [Tool Runtime Context](../../docs/tools-mcp/runtime-context.mdx)
561
+ - [Agent Runtime Context](../../docs/server-db/runtime-context.mdx)
562
+ - [Tool Runtime Context](../../docs/tools-mcp/overview.mdx#using-runtimecontext)
563
563
 
564
564
  ## Usage Without a Mastra Server
565
565
 
@@ -16,6 +16,43 @@ It provides robust vector similarity search capabilities within your existing Po
16
16
  name: "connectionString",
17
17
  type: "string",
18
18
  description: "PostgreSQL connection URL",
19
+ isOptional: true,
20
+ },
21
+ {
22
+ name: "host",
23
+ type: "string",
24
+ description: "PostgreSQL server host",
25
+ isOptional: true,
26
+ },
27
+ {
28
+ name: "port",
29
+ type: "number",
30
+ description: "PostgreSQL server port",
31
+ isOptional: true,
32
+ },
33
+ {
34
+ name: "database",
35
+ type: "string",
36
+ description: "PostgreSQL database name",
37
+ isOptional: true,
38
+ },
39
+ {
40
+ name: "user",
41
+ type: "string",
42
+ description: "PostgreSQL user",
43
+ isOptional: true,
44
+ },
45
+ {
46
+ name: "password",
47
+ type: "string",
48
+ description: "PostgreSQL password",
49
+ isOptional: true,
50
+ },
51
+ {
52
+ name: "ssl",
53
+ type: "boolean | ConnectionOptions",
54
+ description: "Enable SSL or provide custom SSL configuration",
55
+ isOptional: true,
19
56
  },
20
57
  {
21
58
  name: "schemaName",
@@ -24,19 +61,63 @@ It provides robust vector similarity search capabilities within your existing Po
24
61
  "The name of the schema you want the vector store to use. Will use the default schema if not provided.",
25
62
  isOptional: true,
26
63
  },
64
+ {
65
+ name: "max",
66
+ type: "number",
67
+ description: "Maximum number of pool connections (default: 20)",
68
+ isOptional: true,
69
+ },
70
+ {
71
+ name: "idleTimeoutMillis",
72
+ type: "number",
73
+ description: "Idle connection timeout in milliseconds (default: 30000)",
74
+ isOptional: true,
75
+ },
76
+ {
77
+ name: "pgPoolOptions",
78
+ type: "PoolConfig",
79
+ description: "Additional pg pool configuration options",
80
+ isOptional: true,
81
+ },
27
82
  ]}
28
83
  />
29
84
 
30
85
  ## Constructor Examples
31
86
 
32
- You can instantiate `PgVector` using a config object (with optional schemaName):
87
+ ### Connection String
33
88
 
34
89
  ```ts
35
90
  import { PgVector } from "@mastra/pg";
36
91
 
37
92
  const vectorStore = new PgVector({
38
93
  connectionString: "postgresql://user:password@localhost:5432/mydb",
39
- schemaName: "custom_schema", // optional
94
+ });
95
+ ```
96
+
97
+ ### Host/Port/Database Configuration
98
+
99
+ ```ts
100
+ const vectorStore = new PgVector({
101
+ host: "localhost",
102
+ port: 5432,
103
+ database: "mydb",
104
+ user: "postgres",
105
+ password: "password",
106
+ });
107
+ ```
108
+
109
+ ### Advanced Configuration
110
+
111
+ ```ts
112
+ const vectorStore = new PgVector({
113
+ connectionString: "postgresql://user:password@localhost:5432/mydb",
114
+ schemaName: "custom_schema",
115
+ max: 30,
116
+ idleTimeoutMillis: 60000,
117
+ pgPoolOptions: {
118
+ connectionTimeoutMillis: 5000,
119
+ allowExitOnIdle: true,
120
+ },
40
121
  });
41
122
  ```
42
123
 
@@ -173,6 +173,8 @@ export const weatherTool = createTool({
173
173
 
174
174
  ## Related
175
175
 
176
- - [RuntimeContext Example](../../examples/agents/runtime-context.mdx)
177
- - [Tool Runtime Context](../tools-mcp/runtime-context.mdx)
176
+ - [Runtime Context Example](../../examples/agents/runtime-context.mdx)
177
+ - [Agent Runtime Context](../agents/overview.mdx#using-runtimecontext)
178
+ - [Workflow Runtime Context](../workflows/overview.mdx#using-runtimecontext)
179
+ - [Tool Runtime Context](../tools-mcp/overview.mdx#using-runtimecontext)
178
180
  - [Server Middleware Runtime Context](../server-db/middleware.mdx)
@@ -22,6 +22,24 @@ Depending on whether you’re streaming from an **agent** or a **workflow**, onl
22
22
  - **step-finish**: Confirms that a specific step has fully finalized, and may include metadata like the finish reason for that step.
23
23
  - **finish**: When the agent or workflow completes, including usage statistics.
24
24
 
25
+ ## Network event types
26
+
27
+ When using `agent.network()` for multi-agent collaboration, additional event types are emitted to track the orchestration flow:
28
+
29
+ - **routing-agent-start**: The routing agent begins analyzing the task to decide which primitive (agent/workflow/tool) to delegate to.
30
+ - **routing-agent-text-delta**: Incremental text as the routing agent processes the response from the selected primitive.
31
+ - **routing-agent-end**: The routing agent completes its selection, including the selected primitive and reason for selection.
32
+ - **agent-execution-start**: A delegated agent begins execution.
33
+ - **agent-execution-end**: A delegated agent completes execution.
34
+ - **agent-execution-event-\***: Events from the delegated agent's execution (e.g., `agent-execution-event-text-delta`).
35
+ - **workflow-execution-start**: A delegated workflow begins execution.
36
+ - **workflow-execution-end**: A delegated workflow completes execution.
37
+ - **workflow-execution-event-\***: Events from the delegated workflow's execution.
38
+ - **tool-execution-start**: A delegated tool begins execution.
39
+ - **tool-execution-end**: A delegated tool completes execution.
40
+ - **network-execution-event-step-finish**: A network iteration step completes.
41
+ - **network-execution-event-finish**: The entire network execution completes.
42
+
25
43
  ## Inspecting agent streams
26
44
 
27
45
  Iterate over the `stream` with a `for await` loop to inspect all emitted event chunks.
@@ -113,3 +131,93 @@ Below is an example of events that may be emitted. Each event always includes a
113
131
  }
114
132
  }
115
133
  ```
134
+
135
+ ## Inspecting agent networks
136
+
137
+ When using multi-agent collaboration with `agent.network()`, iterate over the stream to track how tasks are delegated and executed across agents, workflows, and tools.
138
+
139
+ ```typescript {3,5} showLineNumbers copy
140
+ const networkAgent = mastra.getAgent("networkAgent");
141
+
142
+ const networkStream = await networkAgent.network("Research dolphins then write a report");
143
+
144
+ for await (const chunk of networkStream) {
145
+ console.log(chunk);
146
+ }
147
+ ```
148
+
149
+ > See [Agent.network()](../../reference/agents/network.mdx) for more information.
150
+
151
+ ### Example network output
152
+
153
+ Network streams emit events that track the orchestration flow. Each iteration begins with routing, followed by execution of the selected primitive.
154
+
155
+ ```typescript {3,13,22,31}
156
+ // Routing agent decides what to do
157
+ {
158
+ type: 'routing-agent-start',
159
+ from: 'NETWORK',
160
+ runId: '7a3b9c2d-1e4f-5a6b-8c9d-0e1f2a3b4c5d',
161
+ payload: {
162
+ agentId: 'routing-agent',
163
+ // ...
164
+ }
165
+ }
166
+ // Routing agent makes a selection
167
+ {
168
+ type: 'routing-agent-end',
169
+ from: 'NETWORK',
170
+ runId: '7a3b9c2d-1e4f-5a6b-8c9d-0e1f2a3b4c5d',
171
+ payload: {
172
+ // ...
173
+ }
174
+ }
175
+ // Delegated agent begins execution
176
+ {
177
+ type: 'agent-execution-start',
178
+ from: 'NETWORK',
179
+ runId: '8b4c0d3e-2f5a-6b7c-9d0e-1f2a3b4c5d6e',
180
+ payload: {
181
+ // ...
182
+ }
183
+ }
184
+ // Events from the delegated agent's execution
185
+ {
186
+ type: 'agent-execution-event-text-delta',
187
+ from: 'NETWORK',
188
+ runId: '8b4c0d3e-2f5a-6b7c-9d0e-1f2a3b4c5d6e',
189
+ payload: {
190
+ type: 'text-delta',
191
+ payload: {
192
+ // ...
193
+ }
194
+ }
195
+ }
196
+ // ...more events
197
+ ```
198
+
199
+ ### Filtering network events
200
+
201
+ You can filter events by type to track specific aspects of the network execution:
202
+
203
+ ```typescript {5-8,11-13,16-18} showLineNumbers copy
204
+ const networkStream = await networkAgent.network("Analyze data and create visualization");
205
+
206
+ for await (const chunk of networkStream) {
207
+ // Track routing decisions
208
+ if (chunk.type === 'routing-agent-end') {
209
+ console.log('Selected:', chunk.payload.resourceType, chunk.payload.resourceId);
210
+ console.log('Reason:', chunk.payload.selectionReason);
211
+ }
212
+
213
+ // Track agent delegations
214
+ if (chunk.type === 'agent-execution-start') {
215
+ console.log('Delegating to agent:', chunk.payload.agentId);
216
+ }
217
+
218
+ // Track workflow delegations
219
+ if (chunk.type === 'workflow-execution-start') {
220
+ console.log('Executing workflow:', chunk.payload.name);
221
+ }
222
+ }
223
+ ```
@@ -49,7 +49,7 @@ Here are some questions to consider:
49
49
  ...
50
50
  ```
51
51
 
52
- ## Agent stream properties
52
+ ### Agent stream properties
53
53
 
54
54
  An agent stream provides access to various response properties:
55
55
 
@@ -78,6 +78,46 @@ for await (const chunk of stream.textStream) {
78
78
  }
79
79
  ```
80
80
 
81
+ ### Using `Agent.network()`
82
+
83
+ The `network()` method enables multi-agent collaboration by executing a network loop where multiple agents can work together to handle complex tasks. The routing agent delegates tasks to appropriate sub-agents, workflows, and tools based on the conversation context.
84
+
85
+ > **Note**: This method is experimental and requires memory to be configured on the agent.
86
+
87
+ ```typescript {3,5-7} showLineNumbers copy
88
+ const testAgent = mastra.getAgent("testAgent");
89
+
90
+ const networkStream = await testAgent.network("Help me organize my day");
91
+
92
+ for await (const chunk of networkStream) {
93
+ console.log(chunk);
94
+ }
95
+ ```
96
+
97
+ > See [Agent.network()](../../reference/agents/network.mdx) for more information.
98
+
99
+ #### Network stream properties
100
+
101
+ The network stream provides access to execution information:
102
+
103
+ - **`networkStream.status`**: Promise resolving to the workflow execution status
104
+ - **`networkStream.result`**: Promise resolving to the complete execution results
105
+ - **`networkStream.usage`**: Promise resolving to token usage information
106
+
107
+ ```typescript {9-11} showLineNumbers copy
108
+ const testAgent = mastra.getAgent("testAgent");
109
+
110
+ const networkStream = await testAgent.network("Research dolphins then write a report");
111
+
112
+ for await (const chunk of networkStream) {
113
+ console.log(chunk);
114
+ }
115
+
116
+ console.log('Final status:', await networkStream.status);
117
+ console.log('Final result:', await networkStream.result);
118
+ console.log('Token usage:', await networkStream.usage);
119
+ ```
120
+
81
121
  ## Streaming with workflows
82
122
 
83
123
  Streaming from a workflow returns a sequence of structured events describing the run lifecycle, rather than incremental text chunks. This event-based format makes it possible to track and respond to workflow progress in real time once a run is created using `.createRunAsync()`.
@@ -87,43 +87,7 @@ export const testTool = createTool({
87
87
 
88
88
  > See [Runtime Context](../server-db/runtime-context.mdx) for more information.
89
89
 
90
- ## Testing tools locally
91
- There are two ways to run and test tools.
90
+ ## Testing with Mastra Playground
92
91
 
93
- <Steps>
92
+ Use the Mastra [Playground](../server-db/local-dev-playground.mdx) to test tools with different inputs, inspect execution results, and verify tool behavior.
94
93
 
95
- ### Mastra Playground
96
-
97
- With the Mastra Dev Server running you can test a tool from the Mastra Playground by visiting [http://localhost:4111/tools](http://localhost:4111/tools) in your browser.
98
-
99
- > For more information, see the [Local Dev Playground](/docs/server-db/local-dev-playground) documentation.
100
-
101
- ### Command line
102
-
103
- Invoke a tool using `.execute()`.
104
-
105
- ```typescript filename="src/test-tool.ts" showLineNumbers copy
106
- import { RuntimeContext } from "@mastra/core/runtime-context";
107
- import { testTool } from "./mastra/tools/test-tool";
108
-
109
- const runtimeContext = new RuntimeContext();
110
-
111
- const result = await testTool.execute({
112
- context: {
113
- value: "foo"
114
- },
115
- runtimeContext
116
- });
117
-
118
- console.log(result);
119
- ```
120
-
121
- > See [createTool()](../../reference/tools/create-tool.mdx) for more information.
122
-
123
- To test this tool, run the following:
124
-
125
- ```bash copy
126
- npx tsx src/test-tool.ts
127
- ```
128
-
129
- </Steps>