@mastra/mcp-docs-server 1.1.35-alpha.2 → 1.1.35-alpha.21

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 (105) hide show
  1. package/.docs/course/03-agent-memory/18-advanced-configuration-semantic-recall.md +48 -4
  2. package/.docs/docs/agents/background-tasks.md +62 -2
  3. package/.docs/docs/agents/processors.md +34 -2
  4. package/.docs/docs/agents/response-caching.md +148 -0
  5. package/.docs/docs/agents/using-tools.md +8 -0
  6. package/.docs/docs/editor/tools.md +1 -1
  7. package/.docs/docs/index.md +2 -2
  8. package/.docs/docs/mastra-platform/configuration.md +1 -1
  9. package/.docs/docs/mastra-platform/overview.md +1 -1
  10. package/.docs/docs/memory/observational-memory.md +63 -14
  11. package/.docs/docs/memory/overview.md +2 -1
  12. package/.docs/docs/memory/semantic-recall.md +68 -6
  13. package/.docs/docs/observability/logging.md +2 -2
  14. package/.docs/docs/observability/metrics/overview.md +4 -4
  15. package/.docs/docs/observability/overview.md +6 -6
  16. package/.docs/docs/observability/tracing/bridges/otel.md +25 -0
  17. package/.docs/docs/observability/tracing/exporters/arize.md +5 -5
  18. package/.docs/docs/observability/tracing/exporters/braintrust.md +37 -0
  19. package/.docs/docs/observability/tracing/exporters/langfuse.md +21 -0
  20. package/.docs/docs/observability/tracing/exporters/{cloud.md → mastra-platform.md} +28 -26
  21. package/.docs/docs/observability/tracing/exporters/{default.md → mastra-storage.md} +56 -19
  22. package/.docs/docs/observability/tracing/exporters/otel.md +79 -2
  23. package/.docs/docs/observability/tracing/overview.md +30 -29
  24. package/.docs/docs/observability/tracing/processors/sensitive-data-filter.md +6 -6
  25. package/.docs/docs/server/mastra-server.md +30 -19
  26. package/.docs/docs/studio/observability.md +4 -4
  27. package/.docs/docs/studio/overview.md +4 -0
  28. package/.docs/docs/workflows/suspend-and-resume.md +28 -1
  29. package/.docs/guides/deployment/inngest.md +29 -8
  30. package/.docs/guides/guide/web-search.md +7 -7
  31. package/.docs/guides/migrations/mastra-cloud.md +6 -6
  32. package/.docs/guides/migrations/upgrade-to-v1/tracing.md +19 -17
  33. package/.docs/models/gateways/azure-openai.md +94 -23
  34. package/.docs/models/gateways/netlify.md +3 -1
  35. package/.docs/models/gateways/openrouter.md +5 -1
  36. package/.docs/models/gateways/vercel.md +2 -1
  37. package/.docs/models/index.md +1 -1
  38. package/.docs/models/providers/deepinfra.md +2 -1
  39. package/.docs/models/providers/deepseek.md +3 -1
  40. package/.docs/models/providers/digitalocean.md +10 -2
  41. package/.docs/models/providers/firepass.md +71 -0
  42. package/.docs/models/providers/google.md +3 -2
  43. package/.docs/models/providers/kilo.md +5 -3
  44. package/.docs/models/providers/kiro.md +110 -0
  45. package/.docs/models/providers/llmgateway.md +8 -2
  46. package/.docs/models/providers/nebius.md +37 -55
  47. package/.docs/models/providers/openai.md +2 -0
  48. package/.docs/models/providers/opencode-go.md +2 -4
  49. package/.docs/models/providers/opencode.md +3 -3
  50. package/.docs/models/providers/poe.md +4 -1
  51. package/.docs/models/providers/qiniu-ai.md +2 -2
  52. package/.docs/models/providers/wafer.ai.md +2 -1
  53. package/.docs/models/providers/xiaomi-token-plan-ams.md +6 -5
  54. package/.docs/models/providers/xiaomi-token-plan-cn.md +6 -5
  55. package/.docs/models/providers/xiaomi-token-plan-sgp.md +6 -5
  56. package/.docs/models/providers/xiaomi.md +2 -2
  57. package/.docs/models/providers/zenmux.md +1 -1
  58. package/.docs/models/providers.md +1 -0
  59. package/.docs/reference/agents/agent.md +2 -0
  60. package/.docs/reference/cli/mastra.md +464 -0
  61. package/.docs/reference/client-js/agents.md +26 -1
  62. package/.docs/reference/client-js/responses.md +4 -0
  63. package/.docs/reference/configuration.md +6 -6
  64. package/.docs/reference/editor/tool-provider.md +3 -3
  65. package/.docs/reference/harness/harness-class.md +23 -8
  66. package/.docs/reference/index.md +3 -0
  67. package/.docs/reference/memory/observational-memory.md +11 -1
  68. package/.docs/reference/observability/metrics/automatic-metrics.md +2 -4
  69. package/.docs/reference/observability/tracing/bridges/datadog.md +2 -2
  70. package/.docs/reference/observability/tracing/bridges/otel.md +26 -4
  71. package/.docs/reference/observability/tracing/configuration.md +6 -3
  72. package/.docs/reference/observability/tracing/exporters/arize.md +1 -1
  73. package/.docs/reference/observability/tracing/exporters/braintrust.md +2 -0
  74. package/.docs/reference/observability/tracing/exporters/cloud-exporter.md +3 -1
  75. package/.docs/reference/observability/tracing/exporters/console-exporter.md +2 -2
  76. package/.docs/reference/observability/tracing/exporters/default-exporter.md +7 -1
  77. package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md +263 -0
  78. package/.docs/reference/observability/tracing/exporters/mastra-storage-exporter.md +194 -0
  79. package/.docs/reference/observability/tracing/exporters/otel.md +12 -8
  80. package/.docs/reference/observability/tracing/instances.md +2 -2
  81. package/.docs/reference/observability/tracing/interfaces.md +37 -2
  82. package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md +22 -0
  83. package/.docs/reference/observability/tracing/span-filtering.md +2 -2
  84. package/.docs/reference/processors/processor-interface.md +74 -12
  85. package/.docs/reference/processors/provider-history-compat.md +132 -0
  86. package/.docs/reference/processors/response-cache.md +114 -0
  87. package/.docs/reference/processors/tool-call-filter.md +28 -0
  88. package/.docs/reference/storage/clickhouse.md +8 -8
  89. package/.docs/reference/storage/cloudflare-d1.md +1 -1
  90. package/.docs/reference/storage/cloudflare.md +1 -1
  91. package/.docs/reference/storage/composite.md +1 -1
  92. package/.docs/reference/storage/convex.md +1 -1
  93. package/.docs/reference/storage/duckdb.md +3 -3
  94. package/.docs/reference/storage/dynamodb.md +1 -1
  95. package/.docs/reference/storage/lance.md +1 -1
  96. package/.docs/reference/storage/libsql.md +1 -1
  97. package/.docs/reference/storage/postgresql.md +1 -1
  98. package/.docs/reference/storage/upstash.md +1 -1
  99. package/.docs/reference/streaming/ChunkType.md +44 -0
  100. package/.docs/reference/streaming/agents/stream.md +18 -2
  101. package/.docs/reference/tools/create-tool.md +46 -0
  102. package/.docs/reference/tools/mcp-client.md +47 -0
  103. package/.docs/reference/workflows/workflow-state-reader.md +113 -0
  104. package/CHANGELOG.md +71 -0
  105. package/package.json +4 -4
@@ -21,27 +21,29 @@ Install the required packages:
21
21
  **npm**:
22
22
 
23
23
  ```bash
24
- npm install @mastra/inngest@latest inngest @inngest/realtime
24
+ npm install @mastra/inngest@latest inngest
25
25
  ```
26
26
 
27
27
  **pnpm**:
28
28
 
29
29
  ```bash
30
- pnpm add @mastra/inngest@latest inngest @inngest/realtime
30
+ pnpm add @mastra/inngest@latest inngest
31
31
  ```
32
32
 
33
33
  **Yarn**:
34
34
 
35
35
  ```bash
36
- yarn add @mastra/inngest@latest inngest @inngest/realtime
36
+ yarn add @mastra/inngest@latest inngest
37
37
  ```
38
38
 
39
39
  **Bun**:
40
40
 
41
41
  ```bash
42
- bun add @mastra/inngest@latest inngest @inngest/realtime
42
+ bun add @mastra/inngest@latest inngest
43
43
  ```
44
44
 
45
+ > **Note:** Requires `inngest@^4` and Inngest Dev Server `v1.18.0` or later. Realtime is built into the SDK in v4, so `@inngest/realtime` and `realtimeMiddleware` are no longer used.
46
+
45
47
  ## Building an Inngest workflow
46
48
 
47
49
  This guide walks through creating a workflow with Inngest and Mastra, demonstrating a counter application that increments a value until it reaches 10.
@@ -54,13 +56,11 @@ In development:
54
56
 
55
57
  ```ts
56
58
  import { Inngest } from 'inngest'
57
- import { realtimeMiddleware } from '@inngest/realtime/middleware'
58
59
 
59
60
  export const inngest = new Inngest({
60
61
  id: 'mastra',
61
62
  baseUrl: 'http://localhost:8288',
62
63
  isDev: true,
63
- middleware: [realtimeMiddleware()],
64
64
  })
65
65
  ```
66
66
 
@@ -68,14 +68,35 @@ In production:
68
68
 
69
69
  ```ts
70
70
  import { Inngest } from 'inngest'
71
- import { realtimeMiddleware } from '@inngest/realtime/middleware'
72
71
 
73
72
  export const inngest = new Inngest({
74
73
  id: 'mastra',
75
- middleware: [realtimeMiddleware()],
76
74
  })
77
75
  ```
78
76
 
77
+ #### Selecting dev or cloud mode with `INNGEST_DEV`
78
+
79
+ The Inngest SDK runs in one of two modes: dev or cloud. From v4 onward, the SDK defaults to cloud mode and requires `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY`. The examples above set the mode in code with `isDev: true`. As an alternative, set the [`INNGEST_DEV` environment variable](https://www.inngest.com/docs/sdk/environment-variables#inngest-dev) so the same client code works across environments:
80
+
81
+ - `INNGEST_DEV=1`: force dev mode. The SDK talks to a local Inngest Dev Server and disables signature verification.
82
+ - `INNGEST_DEV=0`: force cloud mode. The SDK talks to Inngest Cloud and requires event and signing keys.
83
+ - `INNGEST_DEV=<url>`: force dev mode and point the SDK at the Dev Server at `<url>`, for example `http://localhost:8288`.
84
+ - Unset: defaults to cloud mode.
85
+
86
+ When `INNGEST_DEV` is set, you can drop `isDev` and `baseUrl` from the client:
87
+
88
+ ```ts
89
+ import { Inngest } from 'inngest'
90
+
91
+ export const inngest = new Inngest({
92
+ id: 'mastra',
93
+ })
94
+ ```
95
+
96
+ > **Warning:** Do not set `INNGEST_DEV` in production. It disables signature verification, which is required to securely receive events from Inngest Cloud.
97
+
98
+ The `isDev` option on `new Inngest()` overrides `INNGEST_DEV` when both are set.
99
+
79
100
  ### Creating steps
80
101
 
81
102
  Define the individual steps that will compose your workflow:
@@ -17,7 +17,7 @@ Some LLM providers include built-in web search capabilities that can be used dir
17
17
 
18
18
  1. Install dependencies
19
19
 
20
- **Open AI**:
20
+ **OpenAI**:
21
21
 
22
22
  **npm**:
23
23
 
@@ -119,7 +119,7 @@ Some LLM providers include built-in web search capabilities that can be used dir
119
119
 
120
120
  2. Create a new file `src/mastra/agents/searchAgent.ts` and define your agent:
121
121
 
122
- **Open AI**:
122
+ **OpenAI**:
123
123
 
124
124
  ```ts
125
125
  import { Agent } from '@mastra/core/agent'
@@ -128,7 +128,7 @@ Some LLM providers include built-in web search capabilities that can be used dir
128
128
  id: 'search-agent',
129
129
  name: 'Search Agent',
130
130
  instructions: 'You are a search agent that can search the web for information.',
131
- model: 'openai/gpt-5.4',
131
+ model: 'openai/gpt-5.5',
132
132
  })
133
133
  ```
134
134
 
@@ -147,7 +147,7 @@ Some LLM providers include built-in web search capabilities that can be used dir
147
147
 
148
148
  3. Setup the tool:
149
149
 
150
- **Open AI**:
150
+ **OpenAI**:
151
151
 
152
152
  ```ts
153
153
  import { openai } from '@ai-sdk/openai'
@@ -157,7 +157,7 @@ Some LLM providers include built-in web search capabilities that can be used dir
157
157
  id: 'search-agent',
158
158
  name: 'Search Agent',
159
159
  instructions: 'You are a search agent that can search the web for information.',
160
- model: 'openai/gpt-5.4',
160
+ model: 'openai/gpt-5.5',
161
161
  tools: {
162
162
  webSearch: openai.tools.webSearch(),
163
163
  },
@@ -241,7 +241,7 @@ For more control over search behavior, you can integrate external search APIs as
241
241
  id: 'search-agent',
242
242
  name: 'Search Agent',
243
243
  instructions: 'You are a search agent that can search the web for information.',
244
- model: 'openai/gpt-5.4',
244
+ model: 'openai/gpt-5.5',
245
245
  })
246
246
  ```
247
247
 
@@ -293,7 +293,7 @@ For more control over search behavior, you can integrate external search APIs as
293
293
  id: 'search-agent',
294
294
  name: 'Search Agent',
295
295
  instructions: 'You are a search agent that can search the web for information.',
296
- model: 'openai/gpt-5.4',
296
+ model: 'openai/gpt-5.5',
297
297
  tools: {
298
298
  webSearch,
299
299
  },
@@ -235,8 +235,8 @@ export const mastra = new Mastra({
235
235
  import { Mastra } from '@mastra/core/mastra'
236
236
  import {
237
237
  Observability,
238
- DefaultExporter,
239
- CloudExporter,
238
+ MastraStorageExporter,
239
+ MastraPlatformExporter,
240
240
  SensitiveDataFilter,
241
241
  } from '@mastra/observability'
242
242
 
@@ -245,7 +245,7 @@ export const mastra = new Mastra({
245
245
  configs: {
246
246
  default: {
247
247
  serviceName: 'my-app',
248
- exporters: [new DefaultExporter(), new CloudExporter()],
248
+ exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
249
249
  spanOutputProcessors: [new SensitiveDataFilter()],
250
250
  },
251
251
  },
@@ -253,8 +253,8 @@ export const mastra = new Mastra({
253
253
  })
254
254
  ```
255
255
 
256
- - `DefaultExporter` persists traces to your storage backend for [Studio](https://mastra.ai/docs/studio/observability).
257
- - `CloudExporter` Sends observability data to hosted Mastra Studio when `MASTRA_CLOUD_ACCESS_TOKEN` is set.
256
+ - `MastraStorageExporter` persists observability events to Mastra Storage for [Studio](https://mastra.ai/docs/studio/observability).
257
+ - `MastraPlatformExporter` sends observability events to Mastra Platform when `MASTRA_CLOUD_ACCESS_TOKEN` is set.
258
258
  - `SensitiveDataFilter` redacts passwords, tokens, and keys from span data before export.
259
259
 
260
260
  See the [observability overview](https://mastra.ai/docs/observability/overview) for the full configuration, including composite storage with DuckDB for metrics.
@@ -295,7 +295,7 @@ MASTRA_PROJECT_ID="<staging-id>" mastra studio deploy --env-file .env.staging --
295
295
  MASTRA_PROJECT_ID="<production-id>" mastra studio deploy --env-file .env.production --yes
296
296
  ```
297
297
 
298
- Each environment ends up with its own Studio URL and its own observability data. Send `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` per environment so `CloudExporter` routes traces to the correct project.
298
+ Each environment ends up with its own Studio URL and its own observability data. Send `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` per environment so `MastraPlatformExporter` routes traces to the correct project.
299
299
 
300
300
  ## Deploy Server (optional)
301
301
 
@@ -4,7 +4,9 @@ The observability system has been restructured in v1 with a dedicated `@mastra/o
4
4
 
5
5
  > **Observability data stops flowing on upgrade:** If you upgrade Mastra packages to v1 without migrating your `telemetry:` config to `observability:`, the old config is ignored at runtime. Your service will start cleanly with no error, but **no traces, logs, or metrics will be sent anywhere**. If you were sending data to Mastra Cloud, the dashboard will go empty.
6
6
  >
7
- > Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud) — the new platform requires a new access token and a Studio project before `CloudExporter` can route data to it.
7
+ > Complete this migration in the same change that bumps your Mastra packages, and verify traces appear in [Mastra Studio](https://mastra.ai/docs/studio/observability) before considering the upgrade complete. If you previously hosted on Mastra Cloud, also follow the [Mastra Cloud migration guide](https://mastra.ai/guides/migrations/mastra-cloud) — the new platform requires a new access token and a Studio project before `MastraPlatformExporter` can route data to it.
8
+
9
+ > **Exporter rename:** `MastraPlatformExporter` (sends data to Mastra Platform) replaces the previous `CloudExporter`, and `MastraStorageExporter` (persists data to Mastra Storage) replaces the previous `DefaultExporter`. The original classes still ship from `@mastra/observability` and behave identically, but they are deprecated. New code should use `MastraPlatformExporter` and `MastraStorageExporter`; existing imports of `CloudExporter`/`DefaultExporter` continue to work until they are removed in a future major version.
8
10
 
9
11
  ## Migration paths
10
12
 
@@ -38,8 +40,8 @@ export const mastra = new Mastra({
38
40
  import { Mastra } from '@mastra/core'
39
41
  import {
40
42
  Observability,
41
- DefaultExporter,
42
- CloudExporter,
43
+ MastraStorageExporter,
44
+ MastraPlatformExporter,
43
45
  SensitiveDataFilter,
44
46
  } from '@mastra/observability'
45
47
 
@@ -49,8 +51,8 @@ export const mastra = new Mastra({
49
51
  default: {
50
52
  serviceName: 'mastra',
51
53
  exporters: [
52
- new DefaultExporter(), // Persists traces to storage for Studio
53
- new CloudExporter(), // Sends observability data to hosted Mastra Studio (if MASTRA_CLOUD_ACCESS_TOKEN is set)
54
+ new MastraStorageExporter(), // Persists observability events to Mastra Storage
55
+ new MastraPlatformExporter(), // Sends observability events to Mastra Platform (if MASTRA_CLOUD_ACCESS_TOKEN is set)
54
56
  ],
55
57
  spanOutputProcessors: [
56
58
  new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
@@ -61,7 +63,7 @@ export const mastra = new Mastra({
61
63
  })
62
64
  ```
63
65
 
64
- This configuration includes `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter` processor. See the [observability tracing documentation](https://mastra.ai/docs/observability/tracing/overview) for full configuration options.
66
+ This configuration includes `MastraStorageExporter`, `MastraPlatformExporter`, and `SensitiveDataFilter` processor. See the [observability tracing documentation](https://mastra.ai/docs/observability/tracing/overview) for full configuration options.
65
67
 
66
68
  #### After (v1 with custom configuration)
67
69
 
@@ -122,7 +124,7 @@ Key changes:
122
124
 
123
125
  1. Install `@mastra/observability` package
124
126
  2. Replace `telemetry:` with `observability: new Observability()`
125
- 3. Use explicit `configs:` with `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter`
127
+ 3. Use explicit `configs:` with `MastraStorageExporter`, `MastraPlatformExporter`, and `SensitiveDataFilter`
126
128
  4. Export types change from string literals (`'otlp'`) to exporter class instances (`new OtelExporter()`)
127
129
 
128
130
  See the [exporters documentation](https://mastra.ai/docs/observability/tracing/overview) for all available exporters.
@@ -149,8 +151,8 @@ export const mastra = new Mastra({
149
151
  import { Mastra } from '@mastra/core'
150
152
  import {
151
153
  Observability,
152
- DefaultExporter,
153
- CloudExporter,
154
+ MastraStorageExporter,
155
+ MastraPlatformExporter,
154
156
  SensitiveDataFilter,
155
157
  } from '@mastra/observability'
156
158
 
@@ -159,7 +161,7 @@ export const mastra = new Mastra({
159
161
  configs: {
160
162
  default: {
161
163
  serviceName: 'mastra',
162
- exporters: [new DefaultExporter(), new CloudExporter()],
164
+ exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
163
165
  spanOutputProcessors: [new SensitiveDataFilter()],
164
166
  },
165
167
  },
@@ -171,7 +173,7 @@ Key changes:
171
173
 
172
174
  1. Install `@mastra/observability` package
173
175
  2. Import `Observability`, exporters, and processors from `@mastra/observability`
174
- 3. Use explicit `configs` with `DefaultExporter`, `CloudExporter`, and `SensitiveDataFilter`
176
+ 3. Use explicit `configs` with `MastraStorageExporter`, `MastraPlatformExporter`, and `SensitiveDataFilter`
175
177
 
176
178
  ## Changed
177
179
 
@@ -219,8 +221,8 @@ To migrate, use `new Observability()` with explicit exporters and processors.
219
221
  ```diff
220
222
  + import {
221
223
  + Observability,
222
- + DefaultExporter,
223
- + CloudExporter,
224
+ + MastraStorageExporter,
225
+ + MastraPlatformExporter,
224
226
  + SensitiveDataFilter,
225
227
  + } from '@mastra/observability';
226
228
 
@@ -232,7 +234,7 @@ To migrate, use `new Observability()` with explicit exporters and processors.
232
234
  + configs: {
233
235
  + default: {
234
236
  + serviceName: 'mastra',
235
- + exporters: [new DefaultExporter(), new CloudExporter()],
237
+ + exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
236
238
  + spanOutputProcessors: [new SensitiveDataFilter()],
237
239
  + },
238
240
  + },
@@ -320,8 +322,8 @@ Simply remove the `instrumentation.mjs` file and configure observability in your
320
322
  // src/mastra/index.ts
321
323
  import {
322
324
  Observability,
323
- DefaultExporter,
324
- CloudExporter,
325
+ MastraStorageExporter,
326
+ MastraPlatformExporter,
325
327
  SensitiveDataFilter,
326
328
  } from '@mastra/observability'
327
329
 
@@ -330,7 +332,7 @@ export const mastra = new Mastra({
330
332
  configs: {
331
333
  default: {
332
334
  serviceName: 'mastra',
333
- exporters: [new DefaultExporter(), new CloudExporter()],
335
+ exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
334
336
  spanOutputProcessors: [new SensitiveDataFilter()],
335
337
  },
336
338
  },
@@ -13,7 +13,7 @@ const agent = new Agent({
13
13
  id: "my-agent",
14
14
  name: "My Agent",
15
15
  instructions: "You are a helpful assistant",
16
- model: "azure-openai/my-gpt4-deployment" // Use your Azure deployment name (autocompleted in dev mode)
16
+ model: "azure-openai/my-gpt-5-4-deployment" // Use your Azure deployment name (autocompleted in dev mode)
17
17
  });
18
18
 
19
19
  // Generate a response
@@ -34,9 +34,9 @@ Azure model IDs follow this pattern: `azure-openai/your-deployment-name`
34
34
 
35
35
  The deployment name is **specific to your Azure account** and chosen when you create a deployment in Azure Portal. Common examples:
36
36
 
37
- - `azure-openai/my-gpt4-deployment`
38
- - `azure-openai/production-gpt-35-turbo`
39
- - `azure-openai/staging-gpt-4o`
37
+ - `azure-openai/my-gpt-5-4-deployment`
38
+ - `azure-openai/production-gpt-5-4`
39
+ - `azure-openai/staging-gpt-5-4-mini`
40
40
 
41
41
  ## Setup
42
42
 
@@ -44,7 +44,7 @@ Create deployments in [Azure OpenAI Studio](https://oai.azure.com/). The resourc
44
44
 
45
45
  ## Configuration
46
46
 
47
- Instantiate the gateway and pass it to Mastra. Three configuration modes are available.
47
+ Instantiate the gateway and pass it to Mastra. The common configuration modes are shown below.
48
48
 
49
49
  ### Static Deployments
50
50
 
@@ -59,7 +59,7 @@ export const mastra = new Mastra({
59
59
  new AzureOpenAIGateway({
60
60
  resourceName: "my-openai-resource",
61
61
  apiKey: process.env.AZURE_API_KEY!,
62
- deployments: ["gpt-4-prod", "gpt-35-turbo-dev"],
62
+ deployments: ["gpt-5-4-prod", "gpt-5-4-mini-dev"],
63
63
  }),
64
64
  ],
65
65
  });
@@ -111,7 +111,7 @@ export const mastra = new Mastra({
111
111
  type: "entraId",
112
112
  credential: new DefaultAzureCredential(),
113
113
  },
114
- deployments: ["gpt-4-prod", "gpt-35-turbo-dev"],
114
+ deployments: ["gpt-5-4-prod", "gpt-5-4-mini-dev"],
115
115
  }),
116
116
  ],
117
117
  });
@@ -145,23 +145,94 @@ export const mastra = new Mastra({
145
145
  });
146
146
  ```
147
147
 
148
+ ### Azure Responses API
149
+
150
+ Azure OpenAI supports the Responses API through the `v1` API path used by the AI SDK Azure provider. Set `useResponsesAPI: true` when your Azure resource and deployment support that route. The gateway then uses `apiVersion: "v1"` and `useDeploymentBasedUrls: false` by default.
151
+
152
+ ```typescript
153
+ import { Mastra } from "@mastra/core";
154
+ import { AzureOpenAIGateway } from "@mastra/core/llm";
155
+
156
+ export const mastra = new Mastra({
157
+ gateways: [
158
+ new AzureOpenAIGateway({
159
+ resourceName: "my-openai-resource",
160
+ apiKey: process.env.AZURE_API_KEY!,
161
+ useResponsesAPI: true,
162
+ deployments: ["my-gpt-5-4-deployment"],
163
+ }),
164
+ ],
165
+ });
166
+ ```
167
+
168
+ Keep `useResponsesAPI` omitted or set it to `false` for the existing Azure chat completions route. That path keeps `apiVersion: "2024-04-01-preview"` and deployment-based URLs by default for compatibility.
169
+
170
+ You can still configure `apiVersion` and `useDeploymentBasedUrls` directly. For example, set `useDeploymentBasedUrls: false` to use the Azure `v1` URL shape with the chat model constructor; the gateway defaults `apiVersion` to `"v1"` for that route. Passing `apiVersion: "v1"` by itself keeps the existing deployment-based URL default for compatibility.
171
+
172
+ Do not combine `useResponsesAPI: true` with `useDeploymentBasedUrls: true`; the gateway rejects that configuration because Responses API support uses the Azure `v1` route.
173
+
174
+ Use `apiVersion: "v1"` for the GA `v1` route. Microsoft currently exposes preview `v1` features through feature-specific headers, such as `"aoai-evals": "preview"`, or through preview/alpha API paths. The gateway still accepts `apiVersion: "preview"` with `useDeploymentBasedUrls: false` for Azure provider configurations that require the preview query value. Date-based API versions are only for the legacy deployment-based route, so the gateway rejects them when `useResponsesAPI` is `true` or `useDeploymentBasedUrls` is `false`.
175
+
176
+ The same API key and Microsoft Entra ID authentication modes work with the `v1` route.
177
+
178
+ ### Azure Responses WebSocket transport
179
+
180
+ Azure OpenAI also supports WebSocket mode on the Responses API. Use it for agent or tool loops with many model-tool round trips. Keep the standard HTTP transport for single-shot requests and short conversations.
181
+
182
+ WebSocket transport requires `useResponsesAPI: true`, because Azure exposes it on the `v1` Responses path. Then opt in per stream request with `providerOptions.azure.transport: "websocket"`.
183
+
184
+ ```typescript
185
+ import { Agent } from "@mastra/core/agent";
186
+
187
+ const agent = new Agent({
188
+ id: "azure-ws-agent",
189
+ name: "Azure WebSocket Agent",
190
+ instructions: "Use tools when they are useful.",
191
+ model: "azure-openai/my-gpt-5-4-deployment",
192
+ });
193
+
194
+ const stream = await agent.stream("Find and improve the slow function.", {
195
+ providerOptions: {
196
+ azure: {
197
+ transport: "websocket",
198
+ store: false,
199
+ websocket: {
200
+ closeOnFinish: false,
201
+ },
202
+ },
203
+ },
204
+ });
205
+
206
+ for await (const chunk of stream.textStream) {
207
+ process.stdout.write(chunk);
208
+ }
209
+
210
+ stream.transport?.close();
211
+ ```
212
+
213
+ Set `closeOnFinish: false` when you want to keep the socket open across follow-up turns. Azure keeps one response chain in connection-local memory, so continuing from the most recent `previous_response_id` can reduce continuation latency. The connection runs one response at a time and does not multiplex parallel runs.
214
+
215
+ Do not send overlapping follow-up requests with `previous_response_id` on the same WebSocket transport. Mastra rejects overlapping continuation requests because Azure only keeps one in-flight response per connection. Wait for the active stream to finish before continuing the response chain.
216
+
148
217
  ## Configuration Reference
149
218
 
150
- | Option | Type | Required | Description |
151
- | --------------------------- | ----------------- | -------- | --------------------------------------------------------------------- |
152
- | `resourceName` | `string` | Yes | Azure OpenAI resource name |
153
- | `apiKey` | `string` | Yes\* | API key from "Keys and Endpoint" |
154
- | `authentication` | `object` | No | Microsoft Entra ID authentication |
155
- | `authentication.type` | `"entraId"` | Yes\* | Authentication mode |
156
- | `authentication.credential` | `TokenCredential` | Yes\* | Azure SDK-compatible credential for `entraId` authentication mode |
157
- | `authentication.scope` | `string` | No | Token scope (default: `https://cognitiveservices.azure.com/.default`) |
158
- | `apiVersion` | `string` | No | API version (default: `2024-04-01-preview`) |
159
- | `deployments` | `string[]` | No | Deployment names for static mode |
160
- | `management` | `object` | No | Management API credentials |
161
- | `management.tenantId` | `string` | Yes\* | Azure AD tenant ID |
162
- | `management.clientId` | `string` | Yes\* | Service Principal client ID |
163
- | `management.clientSecret` | `string` | Yes\* | Service Principal secret |
164
- | `management.subscriptionId` | `string` | Yes\* | Azure subscription ID |
165
- | `management.resourceGroup` | `string` | Yes\* | Resource group name |
219
+ | Option | Type | Required | Description |
220
+ | --------------------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
221
+ | `resourceName` | `string` | Yes | Azure OpenAI resource name |
222
+ | `apiKey` | `string` | Yes\* | API key from "Keys and Endpoint" |
223
+ | `authentication` | `object` | No | Microsoft Entra ID authentication |
224
+ | `authentication.type` | `"entraId"` | Yes\* | Authentication mode |
225
+ | `authentication.credential` | `TokenCredential` | Yes\* | Azure SDK-compatible credential for `entraId` authentication mode |
226
+ | `authentication.scope` | `string` | No | Token scope (default: `https://cognitiveservices.azure.com/.default`) |
227
+ | `apiVersion` | `string` | No | API version (default: `2024-04-01-preview`, or `v1` when `useResponsesAPI` is `true` or `useDeploymentBasedUrls` is `false`) |
228
+ | `useResponsesAPI` | `boolean` | No | Resolve deployments through the Azure OpenAI Responses API (default: `false`) |
229
+ | `useDeploymentBasedUrls` | `boolean` | No | Use Azure deployment-based URLs (default: `true`, or `false` when `useResponsesAPI` is `true`) |
230
+ | `deployments` | `string[]` | No | Deployment names for static mode |
231
+ | `management` | `object` | No | Management API credentials |
232
+ | `management.tenantId` | `string` | Yes\* | Azure AD tenant ID |
233
+ | `management.clientId` | `string` | Yes\* | Service Principal client ID |
234
+ | `management.clientSecret` | `string` | Yes\* | Service Principal secret |
235
+ | `management.subscriptionId` | `string` | Yes\* | Azure subscription ID |
236
+ | `management.resourceGroup` | `string` | Yes\* | Resource group name |
166
237
 
167
238
  \* Provide either `apiKey` or `authentication.type: "entraId"`. Management fields are required if `management` is provided.
@@ -1,6 +1,6 @@
1
1
  # Netlify
2
2
 
3
- Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 66 models through Mastra's model router.
3
+ Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 68 models through Mastra's model router.
4
4
 
5
5
  Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
6
6
 
@@ -57,11 +57,13 @@ ANTHROPIC_API_KEY=ant-...
57
57
  | `gemini/gemini-3-flash-preview` |
58
58
  | `gemini/gemini-3-pro-image-preview` |
59
59
  | `gemini/gemini-3.1-flash-image-preview` |
60
+ | `gemini/gemini-3.1-flash-lite` |
60
61
  | `gemini/gemini-3.1-flash-lite-preview` |
61
62
  | `gemini/gemini-3.1-pro-preview` |
62
63
  | `gemini/gemini-3.1-pro-preview-customtools` |
63
64
  | `gemini/gemini-flash-latest` |
64
65
  | `gemini/gemini-flash-lite-latest` |
66
+ | `openai/chat-latest` |
65
67
  | `openai/gpt-4.1` |
66
68
  | `openai/gpt-4.1-mini` |
67
69
  | `openai/gpt-4.1-nano` |
@@ -1,6 +1,6 @@
1
1
  # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
2
2
 
3
- OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 185 models through Mastra's model router.
3
+ OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 189 models through Mastra's model router.
4
4
 
5
5
  Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
6
6
 
@@ -172,6 +172,8 @@ ANTHROPIC_API_KEY=ant-...
172
172
  | `poolside/laguna-xs.2:free` |
173
173
  | `prime-intellect/intellect-3` |
174
174
  | `qwen/qwen-2.5-coder-32b-instruct` |
175
+ | `qwen/qwen-3.6-27b` |
176
+ | `qwen/qwen-plus` |
175
177
  | `qwen/qwen2.5-vl-72b-instruct` |
176
178
  | `qwen/qwen3-235b-a22b-07-25` |
177
179
  | `qwen/qwen3-235b-a22b-thinking-2507` |
@@ -180,6 +182,7 @@ ANTHROPIC_API_KEY=ant-...
180
182
  | `qwen/qwen3-coder` |
181
183
  | `qwen/qwen3-coder-30b-a3b-instruct` |
182
184
  | `qwen/qwen3-coder-flash` |
185
+ | `qwen/qwen3-coder-plus` |
183
186
  | `qwen/qwen3-coder:exacto` |
184
187
  | `qwen/qwen3-max` |
185
188
  | `qwen/qwen3-next-80b-a3b-instruct` |
@@ -192,6 +195,7 @@ ANTHROPIC_API_KEY=ant-...
192
195
  | `sourceful/riverflow-v2-max-preview` |
193
196
  | `sourceful/riverflow-v2-standard-preview` |
194
197
  | `stepfun/step-3.5-flash` |
198
+ | `tencent/hy3-preview` |
195
199
  | `x-ai/grok-3` |
196
200
  | `x-ai/grok-3-beta` |
197
201
  | `x-ai/grok-3-mini` |
@@ -1,6 +1,6 @@
1
1
  # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
2
2
 
3
- Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 246 models through Mastra's model router.
3
+ Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 247 models through Mastra's model router.
4
4
 
5
5
  Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
6
6
 
@@ -113,6 +113,7 @@ ANTHROPIC_API_KEY=ant-...
113
113
  | `google/gemini-3-pro-image` |
114
114
  | `google/gemini-3-pro-preview` |
115
115
  | `google/gemini-3.1-flash-image-preview` |
116
+ | `google/gemini-3.1-flash-lite` |
116
117
  | `google/gemini-3.1-flash-lite-preview` |
117
118
  | `google/gemini-3.1-pro-preview` |
118
119
  | `google/gemini-embedding-001` |
@@ -1,6 +1,6 @@
1
1
  # Model Providers
2
2
 
3
- Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3875 models from 107 providers through a single API.
3
+ Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3888 models from 108 providers through a single API.
4
4
 
5
5
  ## Features
6
6
 
@@ -1,6 +1,6 @@
1
1
  # ![Deep Infra logo](https://models.dev/logos/deepinfra.svg)Deep Infra
2
2
 
3
- Access 35 Deep Infra models through Mastra's model router. Authentication is handled automatically using the `DEEPINFRA_API_KEY` environment variable.
3
+ Access 36 Deep Infra models through Mastra's model router. Authentication is handled automatically using the `DEEPINFRA_API_KEY` environment variable.
4
4
 
5
5
  Learn more in the [Deep Infra documentation](https://deepinfra.com/models).
6
6
 
@@ -36,6 +36,7 @@ for await (const chunk of stream) {
36
36
  | `deepinfra/anthropic/claude-4-opus` | 200K | | | | | | $17 | $83 |
37
37
  | `deepinfra/deepseek-ai/DeepSeek-R1-0528` | 164K | | | | | | $0.50 | $2 |
38
38
  | `deepinfra/deepseek-ai/DeepSeek-V3.2` | 164K | | | | | | $0.26 | $0.38 |
39
+ | `deepinfra/deepseek-ai/DeepSeek-V4-Flash` | 1.0M | | | | | | $0.14 | $0.28 |
39
40
  | `deepinfra/deepseek-ai/DeepSeek-V4-Pro` | 66K | | | | | | $2 | $3 |
40
41
  | `deepinfra/google/gemma-4-26B-A4B-it` | 256K | | | | | | $0.07 | $0.34 |
41
42
  | `deepinfra/google/gemma-4-31B-it` | 256K | | | | | | $0.13 | $0.38 |
@@ -87,4 +87,6 @@ const response = await agent.generate("Hello!", {
87
87
 
88
88
  ### Available Options
89
89
 
90
- **thinking** (`{ type?: "enabled" | "disabled" | undefined; } | undefined`)
90
+ **thinking** (`{ type?: "enabled" | "disabled" | undefined; } | undefined`)
91
+
92
+ **reasoningEffort** (`"high" | "max" | undefined`)
@@ -1,6 +1,6 @@
1
1
  # ![DigitalOcean logo](https://models.dev/logos/digitalocean.svg)DigitalOcean
2
2
 
3
- Access 63 DigitalOcean models through Mastra's model router. Authentication is handled automatically using the `DIGITALOCEAN_ACCESS_TOKEN` environment variable.
3
+ Access 71 DigitalOcean models through Mastra's model router. Authentication is handled automatically using the `DIGITALOCEAN_ACCESS_TOKEN` environment variable.
4
4
 
5
5
  Learn more in the [DigitalOcean documentation](https://docs.digitalocean.com/products/gradient-ai-platform/details/models/).
6
6
 
@@ -37,6 +37,7 @@ for await (const chunk of stream) {
37
37
  | `digitalocean/alibaba-qwen3-32b` | 131K | | | | | | $0.25 | $0.55 |
38
38
  | `digitalocean/all-mini-lm-l6-v2` | 256 | | | | | | $0.01 | — |
39
39
  | `digitalocean/anthropic-claude-4.1-opus` | 200K | | | | | | $15 | $75 |
40
+ | `digitalocean/anthropic-claude-4.5-haiku` | 200K | | | | | | $1 | $5 |
40
41
  | `digitalocean/anthropic-claude-4.5-sonnet` | 1.0M | | | | | | $3 | $15 |
41
42
  | `digitalocean/anthropic-claude-4.6-sonnet` | 1.0M | | | | | | $3 | $15 |
42
43
  | `digitalocean/anthropic-claude-haiku-4.5` | 200K | | | | | | $1 | $5 |
@@ -50,6 +51,7 @@ for await (const chunk of stream) {
50
51
  | `digitalocean/bge-reranker-v2-m3` | 8K | | | | | | $0.01 | — |
51
52
  | `digitalocean/deepseek-3.2` | 128K | | | | | | $0.50 | $2 |
52
53
  | `digitalocean/deepseek-r1-distill-llama-70b` | 131K | | | | | | $0.99 | $0.99 |
54
+ | `digitalocean/deepseek-v3` | 164K | | | | | | — | — |
53
55
  | `digitalocean/deepseek-v4-pro` | 1.0M | | | | | | $2 | $3 |
54
56
  | `digitalocean/e5-large-v2` | 512 | | | | | | $0.02 | — |
55
57
  | `digitalocean/fal-ai/elevenlabs/tts/multilingual-v2` | — | | | | | | — | — |
@@ -60,12 +62,16 @@ for await (const chunk of stream) {
60
62
  | `digitalocean/glm-5` | 203K | | | | | | $1 | $3 |
61
63
  | `digitalocean/gte-large-en-v1.5` | 8K | | | | | | $0.09 | — |
62
64
  | `digitalocean/kimi-k2.5` | 262K | | | | | | $0.50 | $3 |
65
+ | `digitalocean/kimi-k2.6` | 262K | | | | | | $0.95 | $4 |
63
66
  | `digitalocean/llama-4-maverick` | 1.0M | | | | | | $0.25 | $0.87 |
64
- | `digitalocean/llama-guard-4-12b` | 128K | | | | | | | |
67
+ | `digitalocean/llama3-8b-instruct` | 131K | | | | | | $0.20 | $0.20 |
65
68
  | `digitalocean/llama3.3-70b-instruct` | 128K | | | | | | $0.65 | $0.65 |
66
69
  | `digitalocean/minimax-m2.5` | 205K | | | | | | $0.30 | $1 |
70
+ | `digitalocean/ministral-3-8b-instruct-2512` | 262K | | | | | | — | — |
67
71
  | `digitalocean/mistral-3-14B` | 262K | | | | | | $0.20 | $0.20 |
72
+ | `digitalocean/mistral-7b-instruct-v0.3` | 33K | | | | | | — | — |
68
73
  | `digitalocean/multi-qa-mpnet-base-dot-v1` | 512 | | | | | | $0.01 | — |
74
+ | `digitalocean/nemotron-3-nano-30b` | 262K | | | | | | — | — |
69
75
  | `digitalocean/nemotron-3-nano-omni` | 66K | | | | | | $0.50 | $0.90 |
70
76
  | `digitalocean/nemotron-nano-12b-v2-vl` | 128K | | | | | | $0.20 | $0.60 |
71
77
  | `digitalocean/nvidia-nemotron-3-super-120b` | 256K | | | | | | $0.30 | $0.65 |
@@ -86,11 +92,13 @@ for await (const chunk of stream) {
86
92
  | `digitalocean/openai-gpt-5.5` | 1.0M | | | | | | $5 | $30 |
87
93
  | `digitalocean/openai-gpt-image-1` | — | | | | | | $5 | $40 |
88
94
  | `digitalocean/openai-gpt-image-1.5` | — | | | | | | $5 | $10 |
95
+ | `digitalocean/openai-gpt-image-2` | — | | | | | | — | — |
89
96
  | `digitalocean/openai-gpt-oss-120b` | 131K | | | | | | $0.10 | $0.70 |
90
97
  | `digitalocean/openai-gpt-oss-20b` | 131K | | | | | | $0.05 | $0.45 |
91
98
  | `digitalocean/openai-o1` | 200K | | | | | | $15 | $60 |
92
99
  | `digitalocean/openai-o3` | 200K | | | | | | $2 | $8 |
93
100
  | `digitalocean/openai-o3-mini` | 200K | | | | | | $1 | $4 |
101
+ | `digitalocean/qwen-2.5-14b-instruct` | 131K | | | | | | — | — |
94
102
  | `digitalocean/qwen3-coder-flash` | 262K | | | | | | $0.45 | $2 |
95
103
  | `digitalocean/qwen3-embedding-0.6b` | 8K | | | | | | $0.04 | — |
96
104
  | `digitalocean/qwen3-tts-voicedesign` | 33K | | | | | | — | — |