@mastra/mcp-docs-server 1.2.14 → 1.2.15-alpha.10
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.
- package/.docs/docs/agents/a2a.md +75 -2
- package/.docs/docs/agents/processors.md +2 -0
- package/.docs/docs/agents/skills.md +15 -1
- package/.docs/docs/capabilities/channels/overview.md +19 -0
- package/.docs/docs/capabilities/subagents.md +23 -5
- package/.docs/docs/connections/overview.md +94 -0
- package/.docs/docs/datasets/running-experiments.md +18 -0
- package/.docs/docs/evals/overview.md +16 -4
- package/.docs/docs/harness/agent-controller.md +6 -0
- package/.docs/docs/harness/overview.md +26 -0
- package/.docs/docs/index.md +1 -1
- package/.docs/docs/mcp/overview.md +10 -0
- package/.docs/docs/memory/multi-user-threads.md +1 -1
- package/.docs/docs/memory/observational-memory.md +1 -1
- package/.docs/docs/memory/semantic-recall.md +2 -1
- package/.docs/docs/memory/working-memory.md +1 -0
- package/.docs/docs/observability/feedback.md +16 -0
- package/.docs/docs/observability/integrations/exporters/mastra-storage.md +1 -0
- package/.docs/docs/server/auth.md +2 -0
- package/.docs/docs/server/mastra-client.md +11 -11
- package/.docs/docs/storage/overview.md +1 -0
- package/.docs/docs/workflows/agents-and-tools.md +2 -2
- package/.docs/docs/workflows/{stored-workflows.md → dynamic-workflows.md} +23 -23
- package/.docs/docs/workflows/snapshots.md +3 -1
- package/.docs/guides/build-your-ui/ai-sdk-ui.md +25 -14
- package/.docs/guides/getting-started/quickstart.md +1 -1
- package/.docs/guides/rag/overview.md +1 -1
- package/.docs/guides/rag/retrieval.md +17 -0
- package/.docs/guides/rag/vector-databases.md +41 -0
- package/.docs/guides/voice/realtime-voice.md +28 -2
- package/.docs/models/gateways/neon.md +20 -14
- package/.docs/models/gateways/netlify.md +1 -2
- package/.docs/models/gateways/openrouter.md +4 -2
- package/.docs/models/gateways/vercel.md +10 -3
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/anthropic.md +2 -2
- package/.docs/models/providers/cortecs.md +2 -1
- package/.docs/models/providers/deepinfra.md +6 -3
- package/.docs/models/providers/digitalocean.md +6 -5
- package/.docs/models/providers/empiriolabs.md +6 -4
- package/.docs/models/providers/friendli.md +8 -9
- package/.docs/models/providers/huggingface.md +4 -1
- package/.docs/models/providers/hyper.md +5 -6
- package/.docs/models/providers/kilo.md +11 -9
- package/.docs/models/providers/llmgateway.md +3 -3
- package/.docs/models/providers/meta.md +7 -5
- package/.docs/models/providers/minimax.md +25 -23
- package/.docs/models/providers/nano-gpt.md +7 -4
- package/.docs/models/providers/neuralwatt.md +2 -1
- package/.docs/models/providers/ofox.md +74 -16
- package/.docs/models/providers/openai.md +28 -26
- package/.docs/models/providers/opencode-go.md +1 -1
- package/.docs/models/providers/opencode.md +2 -3
- package/.docs/models/providers/perplexity-agent.md +24 -24
- package/.docs/models/providers/pioneer.md +27 -1
- package/.docs/models/providers/regolo-ai.md +25 -20
- package/.docs/models/providers/upstage.md +3 -2
- package/.docs/models/providers/vivgrid.md +4 -2
- package/.docs/models/providers/wandb.md +1 -1
- package/.docs/reference/agents/channels.md +22 -1
- package/.docs/reference/agents/generate.md +1 -1
- package/.docs/reference/ai-sdk/chat-route.md +2 -0
- package/.docs/reference/browser/agent-browser.md +1 -1
- package/.docs/reference/browser/mastra-browser.md +1 -1
- package/.docs/reference/browser/stagehand-browser.md +1 -1
- package/.docs/reference/channels/slack-provider.md +2 -0
- package/.docs/reference/client-js/observability.md +22 -0
- package/.docs/reference/client-js/workflows.md +32 -19
- package/.docs/reference/configuration.md +26 -1
- package/.docs/reference/core/{addStoredWorkflow.md → addDynamicWorkflow.md} +10 -10
- package/.docs/reference/core/{addStoredWorkflows.md → addDynamicWorkflows.md} +9 -9
- package/.docs/reference/editor/tool-provider.md +26 -1
- package/.docs/reference/file-based-agents/config.md +22 -21
- package/.docs/reference/file-based-agents/instructions.md +42 -17
- package/.docs/reference/file-based-agents/schedules.md +232 -0
- package/.docs/reference/index.md +7 -3
- package/.docs/reference/observability/metrics/automatic-metrics.md +10 -8
- package/.docs/reference/rag/metadata-filters.md +13 -4
- package/.docs/reference/server/register-api-route.md +2 -0
- package/.docs/reference/server/routes.md +38 -24
- package/.docs/reference/storage/composite.md +58 -0
- package/.docs/reference/storage/oracledb.md +239 -0
- package/.docs/reference/storage/overview.md +9 -9
- package/.docs/reference/storage/retention.md +1 -1
- package/.docs/reference/streaming/agents/stream.md +1 -1
- package/.docs/reference/tools/bedrock-kb-tool.md +117 -0
- package/.docs/reference/tools/mcp-client.md +54 -0
- package/.docs/reference/vectors/oracledb.md +347 -0
- package/.docs/reference/voice/google.md +19 -3
- package/.docs/reference/workflows/{stored-workflow-definition.md → dynamic-workflow-definition.md} +7 -7
- package/.docs/reference/workflows/step.md +40 -0
- package/.docs/reference/workflows/workflow-methods/agent.md +3 -3
- package/.docs/reference/workflows/workflow-methods/tool.md +3 -3
- package/.docs/reference/workspace/daytona-sandbox.md +21 -0
- package/.docs/reference/workspace/workspace-class.md +2 -0
- package/CHANGELOG.md +51 -0
- package/package.json +6 -6
|
@@ -1,22 +1,22 @@
|
|
|
1
1
|
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
2
|
|
|
3
|
-
#
|
|
3
|
+
# Dynamic workflows
|
|
4
4
|
|
|
5
5
|
> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Dynamic workflows are workflow definitions expressed as data instead of code. A definition is a JSON document that describes the workflow's schemas and step graph. Mastra validates the definition and registers it as a runnable workflow, then persists it in storage so it survives process restarts.
|
|
8
8
|
|
|
9
|
-
Because a definition contains no JavaScript closures, anything that can produce JSON can author a workflow: an HTTP client, an LLM, a visual editor, or your own tooling. Once registered, a
|
|
9
|
+
Because a definition contains no JavaScript closures, anything that can produce JSON can author a workflow: an HTTP client, an LLM, a visual editor, or your own tooling. Once registered, a dynamic workflow runs through the same execution API as a code-defined workflow.
|
|
10
10
|
|
|
11
|
-
## When to use
|
|
11
|
+
## When to use dynamic workflows
|
|
12
12
|
|
|
13
|
-
Use
|
|
13
|
+
Use dynamic workflows when users, agents, visual editors, or external systems need to create workflows without changing application code or deploying again.
|
|
14
14
|
|
|
15
|
-
Keep defining workflows with [`createWorkflow()`](https://mastra.ai/docs/workflows/overview) when the workflow belongs in your application source or needs custom step functions.
|
|
15
|
+
Keep defining workflows with [`createWorkflow()`](https://mastra.ai/docs/workflows/overview) when the workflow belongs in your application source or needs custom step functions. Dynamic workflows can invoke agents, tools, and workflows that are already registered on the `Mastra` instance.
|
|
16
16
|
|
|
17
17
|
## Quickstart
|
|
18
18
|
|
|
19
|
-
The following example registers a tool and invokes it from a
|
|
19
|
+
The following example registers a tool and invokes it from a dynamic workflow. It then runs the workflow. `LibSQLStore` persists the definition in `mastra.db`, so Mastra can restore it after a restart.
|
|
20
20
|
|
|
21
21
|
```typescript
|
|
22
22
|
import { Mastra } from '@mastra/core/mastra'
|
|
@@ -46,7 +46,7 @@ const mastra = new Mastra({
|
|
|
46
46
|
tools: { 'create-greeting': greetingTool },
|
|
47
47
|
})
|
|
48
48
|
|
|
49
|
-
await mastra.
|
|
49
|
+
await mastra.addDynamicWorkflow({
|
|
50
50
|
id: 'greeting-workflow',
|
|
51
51
|
description: 'Create a greeting for the supplied name',
|
|
52
52
|
inputSchema: {
|
|
@@ -83,9 +83,9 @@ if (result.status === 'success') {
|
|
|
83
83
|
}
|
|
84
84
|
```
|
|
85
85
|
|
|
86
|
-
The workflow prints `Hello, Ada!`. Calling [`
|
|
86
|
+
The workflow prints `Hello, Ada!`. Calling [`addDynamicWorkflow()`](https://mastra.ai/reference/core/addDynamicWorkflow) validates the definition before it changes storage or the live workflow registry.
|
|
87
87
|
|
|
88
|
-
The definition uses JSON Schema because it must survive a JSON round trip. The `graph` describes which registered components to invoke and how data moves between them. See the [
|
|
88
|
+
The definition uses JSON Schema because it must survive a JSON round trip. The `graph` describes which registered components to invoke and how data moves between them. See the [dynamic workflow definition reference](https://mastra.ai/reference/workflows/dynamic-workflow-definition) for every field and graph entry.
|
|
89
89
|
|
|
90
90
|
## Build and update definitions
|
|
91
91
|
|
|
@@ -93,54 +93,54 @@ A definition can come from any source that produces JSON. For example, an API ro
|
|
|
93
93
|
|
|
94
94
|
```typescript
|
|
95
95
|
const definition = await request.json()
|
|
96
|
-
await mastra.
|
|
96
|
+
await mastra.addDynamicWorkflow(definition)
|
|
97
97
|
```
|
|
98
98
|
|
|
99
99
|
### Register dependencies first
|
|
100
100
|
|
|
101
|
-
Register referenced components on the same `Mastra` instance before adding the
|
|
101
|
+
Register referenced components on the same `Mastra` instance before adding the dynamic workflow. Agent and nested workflow entries use their intrinsic IDs. A tool entry uses its key from the `Mastra` `tools` object, so the quickstart registers the tool under `create-greeting` before referencing that key with `toolId`.
|
|
102
102
|
|
|
103
|
-
Use a `mapping` entry when one step's output doesn't match the next step's input. Mapping entries can read data from the workflow input and previous step results, along with workflow state and request context. The [definition reference](https://mastra.ai/reference/workflows/
|
|
103
|
+
Use a `mapping` entry when one step's output doesn't match the next step's input. Mapping entries can read data from the workflow input and previous step results, along with workflow state and request context. The [definition reference](https://mastra.ai/reference/workflows/dynamic-workflow-definition) lists the supported mapping descriptors.
|
|
104
104
|
|
|
105
105
|
### Replace a workflow
|
|
106
106
|
|
|
107
107
|
Add a new definition with the same `id` to replace the persisted definition and live registration:
|
|
108
108
|
|
|
109
109
|
```typescript
|
|
110
|
-
await mastra.
|
|
110
|
+
await mastra.addDynamicWorkflow(updatedDefinition)
|
|
111
111
|
```
|
|
112
112
|
|
|
113
113
|
New runs use the updated graph. Runs that already started continue with their original graph.
|
|
114
114
|
|
|
115
115
|
### Add nested workflows together
|
|
116
116
|
|
|
117
|
-
When a root workflow references helper workflows that aren't registered yet, add the full set with [`
|
|
117
|
+
When a root workflow references helper workflows that aren't registered yet, add the full set with [`addDynamicWorkflows()`](https://mastra.ai/reference/core/addDynamicWorkflows):
|
|
118
118
|
|
|
119
119
|
```typescript
|
|
120
|
-
await mastra.
|
|
120
|
+
await mastra.addDynamicWorkflows([rootDefinition, helperDefinition])
|
|
121
121
|
```
|
|
122
122
|
|
|
123
123
|
Mastra validates the bundle as a unit and determines the registration order from the dependencies. If validation fails, none of the definitions are registered.
|
|
124
124
|
|
|
125
125
|
### Manage definitions over HTTP
|
|
126
126
|
|
|
127
|
-
Applications don't need direct access to the `Mastra` instance to manage
|
|
127
|
+
Applications don't need direct access to the `Mastra` instance to manage dynamic workflows. Use one of these interfaces:
|
|
128
128
|
|
|
129
|
-
- [Client SDK workflows API](https://mastra.ai/reference/client-js/workflows): Call `
|
|
129
|
+
- [Client SDK workflows API](https://mastra.ai/reference/client-js/workflows): Call `upsertDynamicWorkflow()` from a JavaScript or TypeScript client.
|
|
130
130
|
- [Server routes](https://mastra.ai/reference/server/routes): Send definitions to `POST /api/stored/workflows`.
|
|
131
131
|
|
|
132
|
-
On authenticated servers,
|
|
132
|
+
On authenticated servers, dynamic-workflow management requires the `stored-workflows:read` and `stored-workflows:write` permissions. Running the registered workflow requires `workflows:execute`.
|
|
133
133
|
|
|
134
134
|
### Persist definitions
|
|
135
135
|
|
|
136
136
|
Stored definitions use the `workflowDefinitions` storage domain. On startup, Mastra loads active definitions from storage and registers them in dependency order.
|
|
137
137
|
|
|
138
|
-
Without a storage adapter that supports this domain, `
|
|
138
|
+
Without a storage adapter that supports this domain, `addDynamicWorkflow()` still registers the workflow in memory, but the definition is lost when the process restarts. See the [storage reference](https://mastra.ai/reference/storage/overview) for adapter support.
|
|
139
139
|
|
|
140
140
|
## Related
|
|
141
141
|
|
|
142
|
-
- [
|
|
143
|
-
- [`Mastra.
|
|
144
|
-
- [`Mastra.
|
|
142
|
+
- [Dynamic workflow definition](https://mastra.ai/reference/workflows/dynamic-workflow-definition)
|
|
143
|
+
- [`Mastra.addDynamicWorkflow()`](https://mastra.ai/reference/core/addDynamicWorkflow)
|
|
144
|
+
- [`Mastra.addDynamicWorkflows()`](https://mastra.ai/reference/core/addDynamicWorkflows)
|
|
145
145
|
- [Client SDK workflows API](https://mastra.ai/reference/client-js/workflows)
|
|
146
146
|
- [Server routes](https://mastra.ai/reference/server/routes)
|
|
@@ -81,13 +81,14 @@ Each snapshot includes the `runId`, input, step status (`success`, `suspended`,
|
|
|
81
81
|
|
|
82
82
|
## How snapshots are saved and retrieved
|
|
83
83
|
|
|
84
|
-
Snapshots are saved to the configured storage system. By default, they use libSQL, but you can configure Upstash or
|
|
84
|
+
Snapshots are saved to the configured storage system. By default, they use libSQL, but you can configure Upstash, PostgreSQL, or OracleDB instead. Each snapshot is saved in the `workflow_snapshots` table and identified by the workflow's `runId`.
|
|
85
85
|
|
|
86
86
|
Read more about:
|
|
87
87
|
|
|
88
88
|
- [libSQL Storage](https://mastra.ai/reference/storage/libsql)
|
|
89
89
|
- [Upstash Storage](https://mastra.ai/reference/storage/upstash)
|
|
90
90
|
- [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
|
|
91
|
+
- [OracleDB Storage](https://mastra.ai/reference/storage/oracledb)
|
|
91
92
|
|
|
92
93
|
### Saving snapshots
|
|
93
94
|
|
|
@@ -141,6 +142,7 @@ export const mastra = new Mastra({
|
|
|
141
142
|
|
|
142
143
|
- [libSQL Storage](https://mastra.ai/reference/storage/libsql)
|
|
143
144
|
- [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
|
|
145
|
+
- [OracleDB Storage](https://mastra.ai/reference/storage/oracledb)
|
|
144
146
|
- [MongoDB Storage](https://mastra.ai/reference/storage/mongodb)
|
|
145
147
|
- [Upstash Storage](https://mastra.ai/reference/storage/upstash)
|
|
146
148
|
- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
|
|
@@ -393,16 +393,17 @@ Use Custom UI when you want to:
|
|
|
393
393
|
|
|
394
394
|
Mastra streams data to the frontend as "parts" within messages. Each part has a `type` that determines how to render it. The `@mastra/ai-sdk` package transforms Mastra streams into AI SDK-compatible [UI Message DataParts](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message#datauipart).
|
|
395
395
|
|
|
396
|
-
| Data Part Type
|
|
397
|
-
|
|
|
398
|
-
| `tool-{toolKey}`
|
|
399
|
-
| `data-workflow`
|
|
400
|
-
| `data-workflow-step`
|
|
401
|
-
| `data-network`
|
|
402
|
-
| `data-tool-agent`
|
|
403
|
-
| `data-tool-
|
|
404
|
-
| `data-tool-
|
|
405
|
-
| `data-
|
|
396
|
+
| Data Part Type | Source | Description |
|
|
397
|
+
| ---------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
|
|
398
|
+
| `tool-{toolKey}` | AI SDK built-in | Tool invocation with states: `input-available`, `output-available`, `output-error` |
|
|
399
|
+
| `data-workflow` | `workflowRoute()` | Workflow execution state snapshots with step status and final outputs |
|
|
400
|
+
| `data-workflow-step` | `workflowRoute()` | Workflow step delta with the full payload for the changed step |
|
|
401
|
+
| `data-network` | `networkRoute()` | Agent network execution with ordered steps and outputs |
|
|
402
|
+
| `data-tool-agent` | Nested agent in tool | Compact nested-agent snapshot while the current step is still running |
|
|
403
|
+
| `data-tool-agent-step` | Nested agent in tool | Full nested-agent step payload emitted when a nested step finishes |
|
|
404
|
+
| `data-tool-workflow` | Nested workflow in tool | Workflow output streamed from within a tool's `execute()` |
|
|
405
|
+
| `data-tool-network` | Nested network in tool | Network output streamed from within a tool's `execute()` |
|
|
406
|
+
| `data-{custom}` | `writer.custom()` | Custom events for progress indicators, status updates, etc. |
|
|
406
407
|
|
|
407
408
|
### Rendering tool outputs
|
|
408
409
|
|
|
@@ -1256,7 +1257,7 @@ For a complete implementation, see the [workflow-suspend-resume example](https:/
|
|
|
1256
1257
|
|
|
1257
1258
|
### Nested agent streams in tools
|
|
1258
1259
|
|
|
1259
|
-
Tools can call agents internally and stream the agent's output back to the UI. This creates `data-tool-agent` parts
|
|
1260
|
+
Tools can call agents internally and stream the agent's output back to the UI. This creates compact `data-tool-agent` snapshots while the nested step is still running, `data-tool-agent-step` parts when a nested step finishes, and one full `data-tool-agent` snapshot when the nested run finishes.
|
|
1260
1261
|
|
|
1261
1262
|
The pattern uses:
|
|
1262
1263
|
|
|
@@ -1315,13 +1316,13 @@ export const forecastAgent = new Agent({
|
|
|
1315
1316
|
|
|
1316
1317
|
**Frontend**:
|
|
1317
1318
|
|
|
1318
|
-
Handle `data-tool-agent` parts
|
|
1319
|
+
Handle `data-tool-agent` parts for the live snapshot and `data-tool-agent-step` parts for the completed nested step payload.
|
|
1319
1320
|
|
|
1320
1321
|
```typescript
|
|
1321
1322
|
import { useChat } from '@ai-sdk/react'
|
|
1322
1323
|
import { DefaultChatTransport } from 'ai'
|
|
1323
1324
|
import { useState } from 'react'
|
|
1324
|
-
import type { AgentDataPart } from '@mastra/ai-sdk'
|
|
1325
|
+
import type { AgentDataPart, AgentStepDataPart } from '@mastra/ai-sdk'
|
|
1325
1326
|
|
|
1326
1327
|
export function NestedAgentChat() {
|
|
1327
1328
|
const [input, setInput] = useState('')
|
|
@@ -1361,6 +1362,15 @@ export function NestedAgentChat() {
|
|
|
1361
1362
|
</div>
|
|
1362
1363
|
)
|
|
1363
1364
|
}
|
|
1365
|
+
if (part.type === 'data-tool-agent-step') {
|
|
1366
|
+
const { data } = part as AgentStepDataPart
|
|
1367
|
+
return (
|
|
1368
|
+
<div key={index} className="nested-agent-step">
|
|
1369
|
+
<strong>Completed nested step {data.stepIndex + 1}</strong>
|
|
1370
|
+
{data.step.text && <p>{data.step.text}</p>}
|
|
1371
|
+
</div>
|
|
1372
|
+
)
|
|
1373
|
+
}
|
|
1364
1374
|
return null
|
|
1365
1375
|
})}
|
|
1366
1376
|
</div>
|
|
@@ -1373,7 +1383,8 @@ export function NestedAgentChat() {
|
|
|
1373
1383
|
Key points:
|
|
1374
1384
|
|
|
1375
1385
|
- Piping `fullStream` to `context.writer` creates `data-tool-agent` parts
|
|
1376
|
-
-
|
|
1386
|
+
- Read `data-tool-agent-step` when you need the full payload for the nested step that just finished
|
|
1387
|
+
- The `AgentDataPart` has `id` (on the part) and `data.text` (the current nested-agent text snapshot)
|
|
1377
1388
|
- The tool still returns its own output after the stream completes
|
|
1378
1389
|
|
|
1379
1390
|
For a complete implementation, see the [tool-nested-streams example](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/tool-nested-streams.tsx) in UI Dojo.
|
|
@@ -67,7 +67,7 @@ The basic building block of RAG is document processing. Documents can be chunked
|
|
|
67
67
|
|
|
68
68
|
## Vector storage
|
|
69
69
|
|
|
70
|
-
Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/guides/rag/vector-databases).
|
|
70
|
+
Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, OracleDB, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/guides/rag/vector-databases).
|
|
71
71
|
|
|
72
72
|
## More resources
|
|
73
73
|
|
|
@@ -436,6 +436,23 @@ export const ragAgent = new Agent({
|
|
|
436
436
|
})
|
|
437
437
|
```
|
|
438
438
|
|
|
439
|
+
**OracleDB**:
|
|
440
|
+
|
|
441
|
+
```ts
|
|
442
|
+
import { ORACLEDB_PROMPT } from '@mastra/oracledb'
|
|
443
|
+
|
|
444
|
+
export const ragAgent = new Agent({
|
|
445
|
+
id: 'rag-agent',
|
|
446
|
+
name: 'RAG Agent',
|
|
447
|
+
model: 'openai/gpt-5.6-sol',
|
|
448
|
+
instructions: `
|
|
449
|
+
Process queries using the provided context. Structure responses to be concise and relevant.
|
|
450
|
+
${ORACLEDB_PROMPT}
|
|
451
|
+
`,
|
|
452
|
+
tools: { vectorQueryTool },
|
|
453
|
+
})
|
|
454
|
+
```
|
|
455
|
+
|
|
439
456
|
**S3Vectors**:
|
|
440
457
|
|
|
441
458
|
```ts
|
|
@@ -78,6 +78,35 @@ await store.upsert({
|
|
|
78
78
|
|
|
79
79
|
PostgreSQL with the pgvector extension is a good solution for teams already using PostgreSQL who want to minimize infrastructure complexity. For detailed setup instructions and best practices, see the [official pgvector repository](https://github.com/pgvector/pgvector).
|
|
80
80
|
|
|
81
|
+
**OracleDB**:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { OracleVector } from '@mastra/oracledb'
|
|
85
|
+
|
|
86
|
+
const store = new OracleVector({
|
|
87
|
+
id: 'oracle-vector',
|
|
88
|
+
user: process.env.ORACLE_DATABASE_USER,
|
|
89
|
+
password: process.env.ORACLE_DATABASE_PASSWORD,
|
|
90
|
+
connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
|
|
91
|
+
})
|
|
92
|
+
|
|
93
|
+
await store.createIndex({
|
|
94
|
+
indexName: 'myCollection',
|
|
95
|
+
dimension: 1536,
|
|
96
|
+
indexConfig: { type: 'none' },
|
|
97
|
+
})
|
|
98
|
+
|
|
99
|
+
await store.upsert({
|
|
100
|
+
indexName: 'myCollection',
|
|
101
|
+
vectors: embeddings,
|
|
102
|
+
metadata: chunks.map(chunk => ({ text: chunk.text })),
|
|
103
|
+
})
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Using Oracle Database Vector Search
|
|
107
|
+
|
|
108
|
+
OracleDB stores embeddings in native `VECTOR` columns and metadata in Oracle JSON. Exact search is the default; HNSW and IVF indexes can be configured for tuned deployments.
|
|
109
|
+
|
|
81
110
|
**Pinecone**:
|
|
82
111
|
|
|
83
112
|
```ts
|
|
@@ -410,6 +439,18 @@ Index names must:
|
|
|
410
439
|
- Example: `my_index_123` is valid
|
|
411
440
|
- Example: `my-index` is not valid (contains hyphen)
|
|
412
441
|
|
|
442
|
+
**OracleDB**:
|
|
443
|
+
|
|
444
|
+
Index names are logical Mastra names. OracleDB maps each logical index to a physical Oracle table internally.
|
|
445
|
+
|
|
446
|
+
Logical index names must:
|
|
447
|
+
|
|
448
|
+
- Be non-empty
|
|
449
|
+
- Be 512 characters or fewer
|
|
450
|
+
- Be stable for the lifetime of the vector index
|
|
451
|
+
- Example: `my_collection_123` is valid
|
|
452
|
+
- Example: `customer-support/docs:v1` is valid and is mapped to a safe Oracle table name
|
|
453
|
+
|
|
413
454
|
**Pinecone**:
|
|
414
455
|
|
|
415
456
|
Index names must:
|
|
@@ -378,12 +378,38 @@ Tracing is on by default. Pass `observability: false` to `createLiveKitWorker` t
|
|
|
378
378
|
|
|
379
379
|
## Deployment
|
|
380
380
|
|
|
381
|
-
The worker is a separate process from your Mastra server
|
|
381
|
+
The worker is a separate process from your Mastra server, so `mastra build` needs to emit it as its own entry. Add it to [`bundler.entries`](https://mastra.ai/reference/configuration):
|
|
382
|
+
|
|
383
|
+
```typescript
|
|
384
|
+
import { Mastra } from '@mastra/core'
|
|
385
|
+
|
|
386
|
+
export const mastra = new Mastra({
|
|
387
|
+
bundler: {
|
|
388
|
+
entries: { 'voice-worker': './voice-worker.ts' },
|
|
389
|
+
// Keep LiveKit's native modules out of the bundle. `mastra build` only applies
|
|
390
|
+
// this default when you set no other bundler options, so set it explicitly here.
|
|
391
|
+
externals: true,
|
|
392
|
+
},
|
|
393
|
+
})
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
`mastra build` now writes both processes into `.mastra/output`, sharing one `package.json` and one dependency install:
|
|
397
|
+
|
|
398
|
+
```text
|
|
399
|
+
.mastra/output/
|
|
400
|
+
index.mjs # Mastra server
|
|
401
|
+
voice-worker.mjs # LiveKit worker
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
Deploy that directory as a single artifact and start each process with its own command:
|
|
382
405
|
|
|
383
406
|
```bash
|
|
384
|
-
node
|
|
407
|
+
node .mastra/output/index.mjs # server
|
|
408
|
+
node .mastra/output/voice-worker.mjs start # worker
|
|
385
409
|
```
|
|
386
410
|
|
|
411
|
+
The worker needs the same environment variables as the server, plus `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET`.
|
|
412
|
+
|
|
387
413
|
LiveKit's guidance on sizing, graceful shutdown, and hosting applies unchanged. See [Deploying agents](https://docs.livekit.io/agents/ops/deployment/). Workers connect outbound to LiveKit, so they don't need inbound ports.
|
|
388
414
|
|
|
389
415
|
## How it works
|
|
@@ -2,21 +2,21 @@
|
|
|
2
2
|
|
|
3
3
|
# Neon
|
|
4
4
|
|
|
5
|
-
Neon aggregates models from multiple providers with enhanced features like rate limiting and failover. Access
|
|
5
|
+
Neon aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 42 models through Mastra's model router.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Neon documentation](https://neon.com/docs).
|
|
8
8
|
|
|
9
9
|
## Usage
|
|
10
10
|
|
|
11
11
|
```typescript
|
|
12
|
-
import { Agent } from
|
|
12
|
+
import { Agent } from "@mastra/core/agent";
|
|
13
13
|
|
|
14
14
|
const agent = new Agent({
|
|
15
|
-
id:
|
|
16
|
-
name:
|
|
17
|
-
instructions:
|
|
18
|
-
model:
|
|
19
|
-
})
|
|
15
|
+
id: "my-agent",
|
|
16
|
+
name: "My Agent",
|
|
17
|
+
instructions: "You are a helpful assistant",
|
|
18
|
+
model: "neon/claude-fable-5"
|
|
19
|
+
});
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Neon documentation](https://neon.com/docs) for details.
|
|
@@ -33,37 +33,43 @@ NEON_AI_GATEWAY_TOKEN=your-gateway-key
|
|
|
33
33
|
|
|
34
34
|
| Model |
|
|
35
35
|
| ----------------------------- |
|
|
36
|
+
| `claude-fable-5` |
|
|
36
37
|
| `claude-haiku-4-5` |
|
|
37
38
|
| `claude-opus-4-1` |
|
|
38
39
|
| `claude-opus-4-5` |
|
|
39
40
|
| `claude-opus-4-6` |
|
|
40
41
|
| `claude-opus-4-7` |
|
|
41
42
|
| `claude-opus-4-8` |
|
|
42
|
-
| `claude-
|
|
43
|
+
| `claude-opus-5` |
|
|
43
44
|
| `claude-sonnet-4-5` |
|
|
44
45
|
| `claude-sonnet-4-6` |
|
|
45
|
-
| `
|
|
46
|
-
| `gemini-2-5-pro` |
|
|
46
|
+
| `claude-sonnet-5` |
|
|
47
47
|
| `gemini-3-1-flash-lite` |
|
|
48
48
|
| `gemini-3-1-pro` |
|
|
49
49
|
| `gemini-3-5-flash` |
|
|
50
|
+
| `gemini-3-5-flash-lite` |
|
|
51
|
+
| `gemini-3-6-flash` |
|
|
50
52
|
| `gemini-3-flash` |
|
|
51
|
-
| `gemini-3-pro` |
|
|
52
53
|
| `gemma-3-12b` |
|
|
54
|
+
| `glm-5-2` |
|
|
53
55
|
| `gpt-5` |
|
|
54
56
|
| `gpt-5-1` |
|
|
55
|
-
| `gpt-5-1-codex-max` |
|
|
56
|
-
| `gpt-5-1-codex-mini` |
|
|
57
57
|
| `gpt-5-2` |
|
|
58
|
-
| `gpt-5-2-codex` |
|
|
59
58
|
| `gpt-5-3-codex` |
|
|
60
59
|
| `gpt-5-4` |
|
|
61
60
|
| `gpt-5-4-mini` |
|
|
62
61
|
| `gpt-5-4-nano` |
|
|
62
|
+
| `gpt-5-5` |
|
|
63
|
+
| `gpt-5-5-pro` |
|
|
64
|
+
| `gpt-5-6-luna` |
|
|
65
|
+
| `gpt-5-6-sol` |
|
|
66
|
+
| `gpt-5-6-terra` |
|
|
63
67
|
| `gpt-5-mini` |
|
|
64
68
|
| `gpt-5-nano` |
|
|
65
69
|
| `gpt-oss-120b` |
|
|
66
70
|
| `gpt-oss-20b` |
|
|
71
|
+
| `inkling` |
|
|
72
|
+
| `kimi-k3` |
|
|
67
73
|
| `llama-4-maverick` |
|
|
68
74
|
| `meta-llama-3-1-8b-instruct` |
|
|
69
75
|
| `meta-llama-3-3-70b-instruct` |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Netlify
|
|
4
4
|
|
|
5
|
-
Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access
|
|
5
|
+
Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 66 models through Mastra's model router.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
|
|
8
8
|
|
|
@@ -84,7 +84,6 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
84
84
|
| `openai/gpt-5.2-2025-12-11` |
|
|
85
85
|
| `openai/gpt-5.2-pro` |
|
|
86
86
|
| `openai/gpt-5.2-pro-2025-12-11` |
|
|
87
|
-
| `openai/gpt-5.3-chat-latest` |
|
|
88
87
|
| `openai/gpt-5.3-codex` |
|
|
89
88
|
| `openai/gpt-5.4` |
|
|
90
89
|
| `openai/gpt-5.4-2026-03-05` |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# OpenRouter
|
|
4
4
|
|
|
5
|
-
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access
|
|
5
|
+
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 339 models through Mastra's model router.
|
|
6
6
|
|
|
7
7
|
Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
|
|
8
8
|
|
|
@@ -139,7 +139,8 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
139
139
|
| `inception/mercury-2` |
|
|
140
140
|
| `inclusionai/ling-2.6-1t` |
|
|
141
141
|
| `inclusionai/ling-2.6-flash` |
|
|
142
|
-
| `inclusionai/ling-3.0-flash
|
|
142
|
+
| `inclusionai/ling-3.0-flash` |
|
|
143
|
+
| `inclusionai/ling-3.0-tiny:free` |
|
|
143
144
|
| `inclusionai/ring-2.6-1t` |
|
|
144
145
|
| `kwaipilot/kat-coder-air-v2.5` |
|
|
145
146
|
| `kwaipilot/kat-coder-pro-v2` |
|
|
@@ -155,6 +156,7 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
155
156
|
| `meta-llama/llama-4-scout` |
|
|
156
157
|
| `meta-llama/llama-guard-4-12b` |
|
|
157
158
|
| `meta/muse-spark-1.1` |
|
|
159
|
+
| `meta/muse-spark-1.2` |
|
|
158
160
|
| `microsoft/phi-4` |
|
|
159
161
|
| `microsoft/wizardlm-2-8x22b` |
|
|
160
162
|
| `minimax/minimax-01` |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Vercel
|
|
4
4
|
|
|
5
|
-
Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access
|
|
5
|
+
Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 322 models through Mastra's model router.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
|
|
8
8
|
|
|
@@ -88,7 +88,6 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
88
88
|
| `anthropic/claude-opus-4.8` |
|
|
89
89
|
| `anthropic/claude-opus-4.8-fast` |
|
|
90
90
|
| `anthropic/claude-opus-5` |
|
|
91
|
-
| `anthropic/claude-opus-5-fast` |
|
|
92
91
|
| `anthropic/claude-sonnet-4` |
|
|
93
92
|
| `anthropic/claude-sonnet-4.5` |
|
|
94
93
|
| `anthropic/claude-sonnet-4.6` |
|
|
@@ -110,6 +109,7 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
110
109
|
| `bytedance/seed-1.8` |
|
|
111
110
|
| `bytedance/seedance-2.0` |
|
|
112
111
|
| `bytedance/seedance-2.0-fast` |
|
|
112
|
+
| `bytedance/seedance-2.5` |
|
|
113
113
|
| `bytedance/seedance-v1.0-pro` |
|
|
114
114
|
| `bytedance/seedance-v1.0-pro-fast` |
|
|
115
115
|
| `bytedance/seedance-v1.5-pro` |
|
|
@@ -131,6 +131,10 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
131
131
|
| `deepseek/deepseek-v4-flash` |
|
|
132
132
|
| `deepseek/deepseek-v4-flash-0731` |
|
|
133
133
|
| `deepseek/deepseek-v4-pro` |
|
|
134
|
+
| `fish-audio/s1` |
|
|
135
|
+
| `fish-audio/s2-pro` |
|
|
136
|
+
| `fish-audio/s2.1-pro` |
|
|
137
|
+
| `fish-audio/transcribe-1` |
|
|
134
138
|
| `google/gemini-2.5-flash` |
|
|
135
139
|
| `google/gemini-2.5-flash-image` |
|
|
136
140
|
| `google/gemini-2.5-flash-lite` |
|
|
@@ -162,7 +166,8 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
162
166
|
| `google/veo-3.1-lite-generate-001` |
|
|
163
167
|
| `inception/mercury-2` |
|
|
164
168
|
| `inception/mercury-coder-small` |
|
|
165
|
-
| `inclusionai/ling-3.0-flash
|
|
169
|
+
| `inclusionai/ling-3.0-flash` |
|
|
170
|
+
| `inclusionai/ling-3.0-tiny-free` |
|
|
166
171
|
| `interfaze/interfaze-beta` |
|
|
167
172
|
| `klingai/kling-v2.5-turbo-i2v` |
|
|
168
173
|
| `klingai/kling-v2.5-turbo-t2v` |
|
|
@@ -182,6 +187,8 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
182
187
|
| `meta/llama-4-maverick` |
|
|
183
188
|
| `meta/llama-4-scout` |
|
|
184
189
|
| `meta/muse-spark-1.1` |
|
|
190
|
+
| `meta/muse-spark-1.2` |
|
|
191
|
+
| `meta/muse-spark-1.2-contributor` |
|
|
185
192
|
| `minimax/minimax-h3` |
|
|
186
193
|
| `minimax/minimax-m2` |
|
|
187
194
|
| `minimax/minimax-m2.1` |
|
package/.docs/models/index.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Model Providers
|
|
4
4
|
|
|
5
|
-
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to
|
|
5
|
+
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5457 models from 168 providers through a single API.
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Anthropic
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 13 Anthropic models through Mastra's model router. Authentication is handled automatically using the `ANTHROPIC_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Anthropic documentation](https://docs.anthropic.com/en/docs/about-claude/models).
|
|
8
8
|
|
|
@@ -123,7 +123,7 @@ const response = await agent.generate("Hello!", {
|
|
|
123
123
|
|
|
124
124
|
**inferenceGeo** (`"us" | "global" | undefined`)
|
|
125
125
|
|
|
126
|
-
**fallbacks** (`{ model: string; max_tokens?: number | undefined; thinking?: Record<string, unknown> | undefined; output_config?: Record<string, unknown> | undefined; speed?: "fast" | "standard" | undefined; }[] | undefined`)
|
|
126
|
+
**fallbacks** (`"default" | { model: string; max_tokens?: number | undefined; thinking?: Record<string, unknown> | undefined; output_config?: Record<string, unknown> | undefined; speed?: "fast" | "standard" | undefined; }[] | undefined`)
|
|
127
127
|
|
|
128
128
|
**anthropicBeta** (`string[] | undefined`)
|
|
129
129
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Cortecs
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 106 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Cortecs documentation](https://cortecs.ai).
|
|
8
8
|
|
|
@@ -59,6 +59,7 @@ for await (const chunk of stream) {
|
|
|
59
59
|
| `cortecs/gemini-2.5-pro` | 1.0M | | | | | | $1 | $10 |
|
|
60
60
|
| `cortecs/gemini-3.1-flash-lite` | 1.0M | | | | | | $0.27 | $2 |
|
|
61
61
|
| `cortecs/gemini-3.5-flash` | 1.0M | | | | | | $1 | $9 |
|
|
62
|
+
| `cortecs/gemini-3.5-flash-lite` | 1.0M | | | | | | $0.33 | $3 |
|
|
62
63
|
| `cortecs/gemma-3-27b-it` | 131K | | | | | | $0.10 | $0.30 |
|
|
63
64
|
| `cortecs/gemma-4-26b-a4b-it` | 262K | | | | | | $0.11 | $0.56 |
|
|
64
65
|
| `cortecs/gemma-4-31b-it` | 262K | | | | | | $0.22 | $0.39 |
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Deep Infra
|
|
4
4
|
|
|
5
|
-
Access
|
|
5
|
+
Access 51 Deep Infra models through Mastra's model router. Authentication is handled automatically using the `DEEPINFRA_API_KEY` environment variable.
|
|
6
6
|
|
|
7
7
|
Learn more in the [Deep Infra documentation](https://deepinfra.com/models).
|
|
8
8
|
|
|
@@ -35,6 +35,8 @@ for await (const chunk of stream) {
|
|
|
35
35
|
| Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
|
|
36
36
|
| ------------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
37
37
|
| `deepinfra/deepseek-ai/DeepSeek-R1-0528` | 164K | | | | | | $0.50 | $2 |
|
|
38
|
+
| `deepinfra/deepseek-ai/DeepSeek-V3` | 164K | | | | | | $0.32 | $0.89 |
|
|
39
|
+
| `deepinfra/deepseek-ai/DeepSeek-V3.1` | 164K | | | | | | $0.25 | $0.95 |
|
|
38
40
|
| `deepinfra/deepseek-ai/DeepSeek-V3.2` | 164K | | | | | | $0.26 | $0.38 |
|
|
39
41
|
| `deepinfra/deepseek-ai/DeepSeek-V4-Flash` | 1.0M | | | | | | $0.09 | $0.18 |
|
|
40
42
|
| `deepinfra/deepseek-ai/DeepSeek-V4-Flash-0731` | 1.0M | | | | | | $0.09 | $0.18 |
|
|
@@ -46,14 +48,15 @@ for await (const chunk of stream) {
|
|
|
46
48
|
| `deepinfra/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 1.0M | | | | | | $0.20 | $0.80 |
|
|
47
49
|
| `deepinfra/meta-llama/Llama-4-Scout-17B-16E-Instruct` | 328K | | | | | | $0.10 | $0.30 |
|
|
48
50
|
| `deepinfra/MiniMaxAI/MiniMax-M2.7` | 197K | | | | | | $0.25 | $1 |
|
|
49
|
-
| `deepinfra/MiniMaxAI/MiniMax-M3` | 524K | | | | | | $0.
|
|
51
|
+
| `deepinfra/MiniMaxAI/MiniMax-M3` | 524K | | | | | | $0.28 | $1 |
|
|
50
52
|
| `deepinfra/moonshotai/Kimi-K2.5` | 262K | | | | | | $0.45 | $2 |
|
|
51
53
|
| `deepinfra/moonshotai/Kimi-K2.6` | 262K | | | | | | $0.75 | $4 |
|
|
52
|
-
| `deepinfra/moonshotai/Kimi-K2.7-Code` | 262K | | | | | | $0.
|
|
54
|
+
| `deepinfra/moonshotai/Kimi-K2.7-Code` | 262K | | | | | | $0.68 | $3 |
|
|
53
55
|
| `deepinfra/moonshotai/Kimi-K3` | 1.0M | | | | | | $3 | $14 |
|
|
54
56
|
| `deepinfra/nvidia/Nemotron-3-Nano-30B-A3B` | 262K | | | | | | $0.05 | $0.20 |
|
|
55
57
|
| `deepinfra/openai/gpt-oss-120b` | 131K | | | | | | $0.04 | $0.17 |
|
|
56
58
|
| `deepinfra/openai/gpt-oss-20b` | 131K | | | | | | $0.03 | $0.14 |
|
|
59
|
+
| `deepinfra/Qwen/Qwen3-235B-A22B-Instruct-2507` | 262K | | | | | | $0.09 | $0.55 |
|
|
57
60
|
| `deepinfra/Qwen/Qwen3-32B` | 41K | | | | | | $0.08 | $0.28 |
|
|
58
61
|
| `deepinfra/Qwen/Qwen3-Coder-480B-A35B-Instruct-Turbo` | 262K | | | | | | $0.30 | $1 |
|
|
59
62
|
| `deepinfra/Qwen/Qwen3-Max` | 256K | | | | | | $1 | $6 |
|