@mastra/mcp-docs-server 1.2.25-alpha.5 → 1.2.25-alpha.8
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/harness/agent-controller.md +26 -0
- package/.docs/docs/harness/signal-providers.md +2 -1
- package/.docs/docs/index.md +11 -0
- package/.docs/docs/mastra-platform/deploy.md +7 -3
- package/.docs/docs/mastra-platform/overview.md +1 -0
- package/.docs/docs/mastra-platform/studio.md +32 -0
- package/.docs/docs/sandbox/overview.md +3 -2
- package/.docs/docs/studio/auth.md +2 -0
- package/.docs/models/gateways/netlify.md +2 -1
- package/.docs/models/gateways/openrouter.md +2 -1
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/cloudflare-workers-ai.md +2 -1
- package/.docs/models/providers/crossmodel.md +4 -3
- package/.docs/models/providers/digitalocean.md +1 -1
- package/.docs/models/providers/edenai.md +4 -3
- package/.docs/models/providers/kilo.md +8 -7
- package/.docs/models/providers/llmgateway-providers.md +2 -3
- package/.docs/models/providers/llmgateway.md +1 -1
- package/.docs/models/providers/nano-gpt.md +4 -8
- package/.docs/models/providers/ofox.md +2 -2
- package/.docs/models/providers/opencode-go.md +7 -7
- package/.docs/reference/code-sdk/mount-agent-controller.md +20 -0
- package/.docs/reference/coding-agent/build-base-prompt.md +1 -1
- package/.docs/reference/migrations/upgrade-to-v1/overview.md +1 -1
- package/.docs/reference/observability/tracing/interfaces.md +195 -8
- package/.docs/reference/observability/tracing/spans.md +2 -2
- package/.docs/reference/observability/tracing/trace-query.md +42 -0
- package/.docs/reference/voice/voice.connect.md +38 -29
- package/package.json +4 -4
|
@@ -133,6 +133,32 @@ const session = await controller.createSession({
|
|
|
133
133
|
|
|
134
134
|
Use [`session.thread.create()`](https://mastra.ai/reference/agent-controller/session) and [`session.thread.switch()`](https://mastra.ai/reference/agent-controller/session) to move one live Session between conversations.
|
|
135
135
|
|
|
136
|
+
### List stored messages from the client
|
|
137
|
+
|
|
138
|
+
Use the Agent Controller client to page through a thread's stored messages. Passing an options object returns the messages with pagination metadata:
|
|
139
|
+
|
|
140
|
+
```typescript
|
|
141
|
+
import { MastraClient } from '@mastra/client-js'
|
|
142
|
+
|
|
143
|
+
const client = new MastraClient({ baseUrl: 'http://localhost:4111' })
|
|
144
|
+
const session = client.getAgentController('assistant-controller').session('user-123')
|
|
145
|
+
|
|
146
|
+
const result = await session.listMessages('support-ticket-42', {
|
|
147
|
+
page: 0,
|
|
148
|
+
perPage: 20,
|
|
149
|
+
orderBy: { field: 'createdAt', direction: 'DESC' },
|
|
150
|
+
filter: {
|
|
151
|
+
dateRange: { start: new Date('2026-01-01') },
|
|
152
|
+
},
|
|
153
|
+
})
|
|
154
|
+
|
|
155
|
+
console.log(result.messages)
|
|
156
|
+
console.log(result.total)
|
|
157
|
+
console.log(result.hasMore)
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`page` is zero-indexed. Omitting `perPage` uses the storage default of 40 messages. Use `include` to request a message by ID with adjacent messages. `limit` is a deprecated alias for `perPage`; existing paged callers may use `{ limit, page }`, but must use `perPage` with `orderBy`, `filter`, or `include`. The existing numeric form, `session.listMessages(threadId, limit)`, remains available when you need the newest message window as an array, ordered oldest-first.
|
|
161
|
+
|
|
136
162
|
## Switch modes and models
|
|
137
163
|
|
|
138
164
|
Modes change the instructions and tools used by the shared backing agent without replacing the Session or thread. Configure mode-specific tools and visibility on the controller:
|
|
@@ -210,4 +210,5 @@ For a production provider that watches GitHub pull requests, see the [GitHub Cha
|
|
|
210
210
|
- [Signals](https://mastra.ai/docs/harness/signals)
|
|
211
211
|
- [Notification signals](https://mastra.ai/docs/harness/signals)
|
|
212
212
|
- [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider)
|
|
213
|
-
- [`WebhookSignalProvider` reference](https://mastra.ai/reference/signals/webhook-signal-provider)
|
|
213
|
+
- [`WebhookSignalProvider` reference](https://mastra.ai/reference/signals/webhook-signal-provider)
|
|
214
|
+
- [Mastra Factory](https://factory.mastra.ai/) uses signal providers to integrate with external systems like GitHub and Linear, bringing issues and pull requests into a collaborative work board.
|
package/.docs/docs/index.md
CHANGED
|
@@ -192,6 +192,17 @@ Templates: [Docs Chatbot](https://mastra.ai/templates/docs-chatbot), [Slack Agen
|
|
|
192
192
|
|
|
193
193
|
</details>
|
|
194
194
|
|
|
195
|
+
<details>
|
|
196
|
+
**Software factories**
|
|
197
|
+
|
|
198
|
+
Coordinate coding agents to turn issues into tested code and pull requests. Let people review plans and changes before they're merged.
|
|
199
|
+
|
|
200
|
+
Used by Mastra.
|
|
201
|
+
|
|
202
|
+
Get started with [Mastra Factory](https://factory.mastra.ai/).
|
|
203
|
+
|
|
204
|
+
</details>
|
|
205
|
+
|
|
195
206
|
<details>
|
|
196
207
|
**Internal copilots**
|
|
197
208
|
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
[`mastra deploy`](https://mastra.ai/reference/cli/mastra) is the single command for releasing a Mastra application to the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview).
|
|
8
8
|
|
|
9
|
-
One command builds your project and validates it before
|
|
9
|
+
One command builds your project and validates it before deploying, plus creates the platform project and environment on your first run, deploys, streams build logs, and prints your public URL once the deploy is serving traffic.
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
mastra deploy
|
|
@@ -63,6 +63,10 @@ A local `.env` file is optional. Environment variables stored on the platform ar
|
|
|
63
63
|
> })
|
|
64
64
|
> ```
|
|
65
65
|
|
|
66
|
+
If the build statically finds `backgroundTasks.enabled: true`, the deploy artifact includes a worker manifest. Mastra Cloud automatically provisions or updates a dedicated worker service from the same artifact. No separate toggle or add-on is required.
|
|
67
|
+
|
|
68
|
+
Removing `backgroundTasks` or setting `enabled: false` in a later deploy removes the manifest and spins down the existing worker service. Values that can't be determined statically are omitted from the manifest display, but the worker process still reads the complete configuration from your bundled code.
|
|
69
|
+
|
|
66
70
|
3. Run `mastra deploy` again. Preflight passes, the build uploads, and the CLI streams build logs until the deploy is live. Expect the full build and deploy to take between 30 seconds and a few minutes. The success message prints only when the new version is serving traffic.
|
|
67
71
|
|
|
68
72
|
4. Verify your deployment at the URL printed by the CLI. Append `/api/agents` to confirm it returns a JSON list of your agents.
|
|
@@ -87,7 +91,7 @@ See [Environments](https://mastra.ai/docs/mastra-platform/environments) for the
|
|
|
87
91
|
|
|
88
92
|
## Choose a region
|
|
89
93
|
|
|
90
|
-
|
|
94
|
+
When a deploy creates an environment interactively, select the United States or Europe from the region prompt. To skip the prompt, pass `--region` with the `us` or `eu` shorthand:
|
|
91
95
|
|
|
92
96
|
```bash
|
|
93
97
|
mastra deploy --env production --region eu
|
|
@@ -97,7 +101,7 @@ The region is fixed when the environment is created. Databases attached to an en
|
|
|
97
101
|
|
|
98
102
|
## Preflight checks
|
|
99
103
|
|
|
100
|
-
Preflight validates the built output before
|
|
104
|
+
Preflight validates the built output before the deploy uploads and only flags issues in your own code:
|
|
101
105
|
|
|
102
106
|
- **Local storage paths**: A hard block. File-backed storage (for example `file:./mastra.db`) is lost on every deploy. Preflight passes when the path is guarded by an environment variable that's set locally or stored on the platform, including values provided by a managed database:
|
|
103
107
|
|
|
@@ -23,6 +23,7 @@ Choose the path that matches what you want to do:
|
|
|
23
23
|
- **Add hosted observability**: Use [Observability](https://mastra.ai/docs/mastra-platform/observability) to collect searchable traces, logs, and metrics across projects and deploys. Start here if you want monitoring without deploying Studio or Server first.
|
|
24
24
|
- **Deploy Studio**: Use [Studio](https://mastra.ai/docs/mastra-platform/studio) to host the visual development environment for your team. Start here if you want a shared UI for testing agents and running workflows, as well as inspecting traces.
|
|
25
25
|
- **Deploy Server**: Use [Server](https://mastra.ai/docs/mastra-platform/server) to run your Mastra application as a production API server. Start here when you’re ready to serve agents, tools, and workflows from the cloud.
|
|
26
|
+
- **Build a software factory:** Deploy [Mastra Factory](https://factory.mastra.ai) to Mastra platform and connect your repository to turn issues into plans, implementations, and reviewed pull requests.
|
|
26
27
|
|
|
27
28
|
## Key concepts
|
|
28
29
|
|
|
@@ -56,6 +56,38 @@ A deploy transitions through **queued → uploading → starting → running** o
|
|
|
56
56
|
|
|
57
57
|
See the [`mastra deploy` CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags and CI/CD usage.
|
|
58
58
|
|
|
59
|
+
## Authentication
|
|
60
|
+
|
|
61
|
+
By default, every Studio deploy on Mastra platform is protected by platform auth. Members of your platform organization sign in with their platform account, and no one else can access the deployed Studio. You don't need to configure anything to get this behavior.
|
|
62
|
+
|
|
63
|
+
Platform auth applies to the Studio UI only. Your server's API routes are governed by your own [`server.auth`](https://mastra.ai/docs/studio/auth) configuration, or remain open if you haven't set one.
|
|
64
|
+
|
|
65
|
+
### Roles and permissions
|
|
66
|
+
|
|
67
|
+
Platform auth maps your organization roles to Studio permissions:
|
|
68
|
+
|
|
69
|
+
| Platform role | Studio permissions |
|
|
70
|
+
| ------------- | ------------------ |
|
|
71
|
+
| `admin` | Full access (`*`) |
|
|
72
|
+
| `member` | Read and execute |
|
|
73
|
+
| `viewer` | Read-only |
|
|
74
|
+
|
|
75
|
+
To customize this mapping, set `roleMapping` on `studio.rbac` in your Mastra configuration. When present, your mapping replaces the platform defaults. See [Role-based access control](https://mastra.ai/docs/studio/auth) for the permission format.
|
|
76
|
+
|
|
77
|
+
### Bring your own auth
|
|
78
|
+
|
|
79
|
+
To use your own auth provider for the deployed Studio instead of platform auth, set an environment variable on the project:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
MASTRA_PLATFORM_STUDIO_AUTH=disabled
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Add it to the env file you deploy with, or store it on the project through the dashboard, then redeploy. With platform auth disabled, the deploy leaves your auth and RBAC configuration untouched. Your own provider drives the Studio login flow, exactly like a self-hosted deploy. `studio.auth` protects the Studio UI, while `server.auth` protects your API routes. Studio requests fall back to `server.auth` when `studio.auth` isn't set.
|
|
86
|
+
|
|
87
|
+
> **Warning:** Disabling platform auth turns off platform account logins. If you disable it without configuring your own auth provider, the deployed Studio and all API routes are publicly accessible.
|
|
88
|
+
|
|
89
|
+
If you keep platform auth enabled and also configure your own `studio.auth`, both providers validate tokens, but the login screen only offers the platform sign-in flow. To sign in through your own provider, disable platform auth.
|
|
90
|
+
|
|
59
91
|
## Environment files
|
|
60
92
|
|
|
61
93
|
A local env file is optional. When a `.env` or `.env.*` file is present in the project directory, the deploy bundles its environment variables.
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
A sandbox gives your agent an isolated environment where it can run commands, execute code, install dependencies, and manage processes. This lets agents perform work that would be risky, resource-intensive, or impractical to run directly inside your application.
|
|
8
8
|
|
|
9
|
-
Sandboxes are often temporary, so files created inside them may disappear when the environment stops. A [filesystem](https://mastra.ai/docs/sandbox/filesystem) gives the agent a place to read, write, and [search](https://mastra.ai/docs/sandbox/search) files that can outlive the sandbox. You can use one to keep outputs between runs, seed a new sandbox with existing files, or give the agent documents it can search while working. Filesystems also work without a sandbox, for example when an agent only needs a knowledge base or access to files in a service such as Google Drive.
|
|
9
|
+
Sandboxes are often temporary, so files created inside them may disappear when the environment stops. A [filesystem](https://mastra.ai/docs/sandbox/filesystem) gives the agent a place to read, write, and [search](https://mastra.ai/docs/sandbox/search) files that can outlive the sandbox. You can use one to keep outputs between runs, seed a new sandbox with existing files, or give the agent documents it can search while working. Filesystems also work without a sandbox, for example when an agent only needs a knowledge base or access to files in a service such as Google Drive. A real-world example is [Mastra Factory](https://factory.mastra.ai/) which uses sandboxes to give coding-agent sessions an environment for repository checkouts, dependencies, and commands.
|
|
10
10
|
|
|
11
11
|
## When to use sandboxes
|
|
12
12
|
|
|
@@ -344,4 +344,5 @@ await sandbox.executeCommand('node', ['scripts/download-reports.js'], {
|
|
|
344
344
|
|
|
345
345
|
- [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager)
|
|
346
346
|
- [Sandbox provider interface](https://mastra.ai/reference/workspace/sandbox)
|
|
347
|
-
- [Filesystem](https://mastra.ai/docs/sandbox/filesystem)
|
|
347
|
+
- [Filesystem](https://mastra.ai/docs/sandbox/filesystem)
|
|
348
|
+
- [Mastra Factory](https://factory.mastra.ai)
|
|
@@ -8,6 +8,8 @@ When you configure [authentication](https://mastra.ai/docs/auth/overview) on you
|
|
|
8
8
|
|
|
9
9
|
Without authentication, Studio and all API routes are publicly accessible.
|
|
10
10
|
|
|
11
|
+
> **Note:** Studio deployed on Mastra platform works differently. By default, the platform injects its own auth so only your organization members can sign in, and your `server.auth` applies to API routes only. Set `MASTRA_PLATFORM_STUDIO_AUTH=disabled` to opt out. See [Authentication on Mastra platform](https://mastra.ai/docs/mastra-platform/studio).
|
|
12
|
+
|
|
11
13
|
## When to use Studio Auth
|
|
12
14
|
|
|
13
15
|
- Multiple team members need to interact with agents, workflows, and tools through a shared Studio deployment.
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Netlify
|
|
6
6
|
|
|
7
|
-
Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access
|
|
7
|
+
Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 251 models through Mastra's model router.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
|
|
10
10
|
|
|
@@ -146,6 +146,7 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
146
146
|
| `openrouter/deepseek/deepseek-v4-flash-vision-exp` |
|
|
147
147
|
| `openrouter/deepseek/deepseek-v4-pro` |
|
|
148
148
|
| `openrouter/deepseek/deepseek-v4-pro-0813` |
|
|
149
|
+
| `openrouter/deepseek/deepseek-v4.1-flash` |
|
|
149
150
|
| `openrouter/google/gemma-2-27b-it` |
|
|
150
151
|
| `openrouter/google/gemma-3-12b-it` |
|
|
151
152
|
| `openrouter/google/gemma-3-27b-it` |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# OpenRouter
|
|
6
6
|
|
|
7
|
-
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access
|
|
7
|
+
OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 358 models through Mastra's model router.
|
|
8
8
|
|
|
9
9
|
Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
|
|
10
10
|
|
|
@@ -105,6 +105,7 @@ ANTHROPIC_API_KEY=ant-...
|
|
|
105
105
|
| `deepseek/deepseek-v4-flash-vision-exp` |
|
|
106
106
|
| `deepseek/deepseek-v4-pro` |
|
|
107
107
|
| `deepseek/deepseek-v4-pro-0813` |
|
|
108
|
+
| `deepseek/deepseek-v4.1-flash` |
|
|
108
109
|
| `dots-studio/dots-3-note-preview:free` |
|
|
109
110
|
| `google/gemini-2.5-flash` |
|
|
110
111
|
| `google/gemini-2.5-flash-image` |
|
package/.docs/models/index.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Model Providers
|
|
6
6
|
|
|
7
|
-
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to
|
|
7
|
+
Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7132 models from 200 providers through a single API.
|
|
8
8
|
|
|
9
9
|
## Features
|
|
10
10
|
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Cloudflare Workers AI
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 27 Cloudflare Workers AI models through Mastra's model router. Authentication is handled automatically using the `CLOUDFLARE_API_KEY` environment variable. Configure `CLOUDFLARE_ACCOUNT_ID` as well.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Cloudflare Workers AI documentation](https://developers.cloudflare.com/workers-ai/models/).
|
|
10
10
|
|
|
@@ -64,6 +64,7 @@ for await (const chunk of stream) {
|
|
|
64
64
|
| `cloudflare-workers-ai/@cf/qwen/qwq-32b` | 24K | | | | | | $0.66 | $1 |
|
|
65
65
|
| `cloudflare-workers-ai/@cf/zai-org/glm-4.7-flash` | 131K | | | | | | $0.06 | $0.40 |
|
|
66
66
|
| `cloudflare-workers-ai/@cf/zai-org/glm-5.2` | 262K | | | | | | $1 | $4 |
|
|
67
|
+
| `cloudflare-workers-ai/@cf/zai-org/glm-5.3` | 1.3M | | | | | | $1 | $4 |
|
|
67
68
|
| `cloudflare-workers-ai/@cf/zai-org/glm-5.3-flash` | 1.3M | | | | | | $0.15 | $0.50 |
|
|
68
69
|
|
|
69
70
|
Model availability, capabilities, context windows, and pricing are sourced from [models.dev](https://models.dev) and may change.
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# CrossModel
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 59 CrossModel models through Mastra's model router. Authentication is handled automatically using the `CROSSMODEL_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [CrossModel documentation](https://www.crossmodel.ai/docs).
|
|
10
10
|
|
|
@@ -46,9 +46,10 @@ for await (const chunk of stream) {
|
|
|
46
46
|
| `crossmodel/anthropic/claude-opus-5` | 1.0M | | | | | | $5 | $25 |
|
|
47
47
|
| `crossmodel/anthropic/claude-sonnet-4-6` | 1.0M | | | | | | $3 | $15 |
|
|
48
48
|
| `crossmodel/anthropic/claude-sonnet-5` | 1.0M | | | | | | $2 | $10 |
|
|
49
|
-
| `crossmodel/deepseek/deepseek-v4-flash` | 1.0M | | | | | | $0.
|
|
50
|
-
| `crossmodel/deepseek/deepseek-v4-flash-vision-exp` | 1.0M | | | | | | $0.
|
|
49
|
+
| `crossmodel/deepseek/deepseek-v4-flash` | 1.0M | | | | | | $0.27 | $1 |
|
|
50
|
+
| `crossmodel/deepseek/deepseek-v4-flash-vision-exp` | 1.0M | | | | | | $0.27 | $1 |
|
|
51
51
|
| `crossmodel/deepseek/deepseek-v4-pro` | 1.0M | | | | | | $1 | $4 |
|
|
52
|
+
| `crossmodel/deepseek/deepseek-v4.1-flash` | 1.0M | | | | | | $0.27 | $1 |
|
|
52
53
|
| `crossmodel/gemini/gemini-2.5-flash` | 1.0M | | | | | | $0.30 | $3 |
|
|
53
54
|
| `crossmodel/gemini/gemini-2.5-flash-lite` | 1.0M | | | | | | $0.10 | $0.40 |
|
|
54
55
|
| `crossmodel/gemini/gemini-2.5-pro` | 1.0M | | | | | | $1 | $10 |
|
|
@@ -79,7 +79,7 @@ for await (const chunk of stream) {
|
|
|
79
79
|
| `digitalocean/gte-large-en-v1.5` | 8K | | | | | | $0.09 | — |
|
|
80
80
|
| `digitalocean/kimi-k2.5` | 262K | | | | | | $0.50 | $3 |
|
|
81
81
|
| `digitalocean/kimi-k2.6` | 262K | | | | | | $0.95 | $4 |
|
|
82
|
-
| `digitalocean/kimi-k3` | 1.0M | | | | | | $3 | $
|
|
82
|
+
| `digitalocean/kimi-k3` | 1.0M | | | | | | $3 | $13 |
|
|
83
83
|
| `digitalocean/llama-4-maverick` | 128K | | | | | | $0.20 | $0.70 |
|
|
84
84
|
| `digitalocean/llama3-8b-instruct` | 131K | | | | | | $0.20 | $0.20 |
|
|
85
85
|
| `digitalocean/llama3.3-70b-instruct` | 128K | | | | | | $0.65 | $0.65 |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Eden AI
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 259 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Eden AI documentation](https://docs.edenai.co).
|
|
10
10
|
|
|
@@ -169,6 +169,7 @@ for await (const chunk of stream) {
|
|
|
169
169
|
| `edenai/moonshot/kimi-k2.7-code-highspeed` | 262K | | | | | | $2 | $8 |
|
|
170
170
|
| `edenai/moonshot/kimi-k3` | 1.0M | | | | | | $3 | $15 |
|
|
171
171
|
| `edenai/nebius/deepseek-ai/DeepSeek-V4-Flash-0731` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
172
|
+
| `edenai/nebius/deepseek-ai/DeepSeek-V4-Pro-0813` | 979K | | | | | | $1 | $4 |
|
|
172
173
|
| `edenai/nebius/meta-llama/Llama-3.3-70B-Instruct` | 131K | | | | | | $0.13 | $0.40 |
|
|
173
174
|
| `edenai/nebius/nvidia/nemotron-3-super-120b-a12b` | 262K | | | | | | $0.30 | $0.90 |
|
|
174
175
|
| `edenai/nebius/nvidia/Nemotron-3-Ultra-550b-a55b` | 1.0M | | | | | | $1 | $3 |
|
|
@@ -216,8 +217,8 @@ for await (const chunk of stream) {
|
|
|
216
217
|
| `edenai/perplexityai/sonar-deep-research` | 128K | | | | | | $2 | $8 |
|
|
217
218
|
| `edenai/perplexityai/sonar-pro` | 200K | | | | | | $3 | $15 |
|
|
218
219
|
| `edenai/perplexityai/sonar-reasoning-pro` | 128K | | | | | | $2 | $8 |
|
|
219
|
-
| `edenai/qwen/deepseek-v4-flash-0731` | 1.0M | | | | | | $0.
|
|
220
|
-
| `edenai/qwen/deepseek-v4-pro-0813` | 1.0M | | | | | | $
|
|
220
|
+
| `edenai/qwen/deepseek-v4-flash-0731` | 1.0M | | | | | | $0.35 | $1 |
|
|
221
|
+
| `edenai/qwen/deepseek-v4-pro-0813` | 1.0M | | | | | | $1 | $3 |
|
|
221
222
|
| `edenai/qwen/qwen-max` | 33K | | | | | | $2 | $6 |
|
|
222
223
|
| `edenai/qwen/qwen-vl-max` | 131K | | | | | | $0.80 | $3 |
|
|
223
224
|
| `edenai/qwen/qwen-vl-plus` | 131K | | | | | | $0.21 | $0.63 |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Kilo Gateway
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 367 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Kilo Gateway documentation](https://kilo.ai).
|
|
10
10
|
|
|
@@ -49,7 +49,7 @@ for await (const chunk of stream) {
|
|
|
49
49
|
| `kilo/~openai/gpt-latest` | 1.1M | | | | | | $2 | $10 |
|
|
50
50
|
| `kilo/~openai/gpt-mini-latest` | 400K | | | | | | $0.75 | $5 |
|
|
51
51
|
| `kilo/~x-ai/grok-latest` | 500K | | | | | | $2 | $6 |
|
|
52
|
-
| `kilo/~z-ai/glm-flash-latest` | 1.0M | | | | | | $0.07 | $0.
|
|
52
|
+
| `kilo/~z-ai/glm-flash-latest` | 1.0M | | | | | | $0.07 | $0.25 |
|
|
53
53
|
| `kilo/~z-ai/glm-latest` | 1.0M | | | | | | $1 | $3 |
|
|
54
54
|
| `kilo/aion-labs/aion-2.0` | 131K | | | | | | $0.80 | $2 |
|
|
55
55
|
| `kilo/aion-labs/aion-3.0` | 131K | | | | | | $3 | $6 |
|
|
@@ -91,7 +91,7 @@ for await (const chunk of stream) {
|
|
|
91
91
|
| `kilo/cohere/command-r-plus-08-2024` | 128K | | | | | | $3 | $10 |
|
|
92
92
|
| `kilo/cohere/command-r7b-12-2024` | 128K | | | | | | $0.04 | $0.15 |
|
|
93
93
|
| `kilo/cohere/north-mini-code:free` | 256K | | | | | | — | — |
|
|
94
|
-
| `kilo/deepseek/deepseek-chat` |
|
|
94
|
+
| `kilo/deepseek/deepseek-chat` | 128K | | | | | | $0.26 | $1 |
|
|
95
95
|
| `kilo/deepseek/deepseek-chat-v3-0324` | 164K | | | | | | $0.29 | $1 |
|
|
96
96
|
| `kilo/deepseek/deepseek-chat-v3.1` | 164K | | | | | | $0.27 | $1 |
|
|
97
97
|
| `kilo/deepseek/deepseek-r1` | 64K | | | | | | $0.70 | $3 |
|
|
@@ -105,6 +105,7 @@ for await (const chunk of stream) {
|
|
|
105
105
|
| `kilo/deepseek/deepseek-v4-flash-vision-exp` | 1.0M | | | | | | $0.44 | $1 |
|
|
106
106
|
| `kilo/deepseek/deepseek-v4-pro` | 1.0M | | | | | | $2 | $3 |
|
|
107
107
|
| `kilo/deepseek/deepseek-v4-pro-0813` | 1.0M | | | | | | $1 | $4 |
|
|
108
|
+
| `kilo/deepseek/deepseek-v4.1-flash` | 1.0M | | | | | | $0.30 | $1 |
|
|
108
109
|
| `kilo/dots-studio/dots-3-note-preview:free` | 512K | | | | | | — | — |
|
|
109
110
|
| `kilo/google/gemini-2.5-flash` | 1.0M | | | | | | $0.30 | $3 |
|
|
110
111
|
| `kilo/google/gemini-2.5-flash-image` | 33K | | | | | | $0.15 | $1 |
|
|
@@ -175,7 +176,7 @@ for await (const chunk of stream) {
|
|
|
175
176
|
| `kilo/minimax/minimax-m2` | 205K | | | | | | $0.30 | $1 |
|
|
176
177
|
| `kilo/minimax/minimax-m2-her` | 66K | | | | | | $0.30 | $1 |
|
|
177
178
|
| `kilo/minimax/minimax-m2.1` | 205K | | | | | | $0.30 | $1 |
|
|
178
|
-
| `kilo/minimax/minimax-m2.5` |
|
|
179
|
+
| `kilo/minimax/minimax-m2.5` | 205K | | | | | | $0.30 | $1 |
|
|
179
180
|
| `kilo/minimax/minimax-m2.7` | 205K | | | | | | $0.30 | $1 |
|
|
180
181
|
| `kilo/minimax/minimax-m3` | 524K | | | | | | $0.30 | $1 |
|
|
181
182
|
| `kilo/mistralai/codestral-2508` | 256K | | | | | | $0.30 | $0.90 |
|
|
@@ -307,7 +308,7 @@ for await (const chunk of stream) {
|
|
|
307
308
|
| `kilo/qwen/qwen3-235b-a22b-2507` | 262K | | | | | | $0.15 | $0.60 |
|
|
308
309
|
| `kilo/qwen/qwen3-235b-a22b-thinking-2507` | 131K | | | | | | $0.23 | $2 |
|
|
309
310
|
| `kilo/qwen/qwen3-30b-a3b` | 41K | | | | | | $0.13 | $0.52 |
|
|
310
|
-
| `kilo/qwen/qwen3-30b-a3b-instruct-2507` |
|
|
311
|
+
| `kilo/qwen/qwen3-30b-a3b-instruct-2507` | 262K | | | | | | $0.13 | $0.52 |
|
|
311
312
|
| `kilo/qwen/qwen3-30b-a3b-thinking-2507` | 82K | | | | | | $0.20 | $2 |
|
|
312
313
|
| `kilo/qwen/qwen3-32b` | 41K | | | | | | $0.08 | $0.28 |
|
|
313
314
|
| `kilo/qwen/qwen3-8b` | 131K | | | | | | $0.12 | $0.46 |
|
|
@@ -368,13 +369,13 @@ for await (const chunk of stream) {
|
|
|
368
369
|
| `kilo/tencent/hy-mt2-1.8b` | 8K | | | | | | $0.04 | $0.18 |
|
|
369
370
|
| `kilo/tencent/hy-mt2-30b-a3b` | 8K | | | | | | $0.07 | $0.29 |
|
|
370
371
|
| `kilo/tencent/hy-mt2-7b` | 8K | | | | | | $0.07 | $0.29 |
|
|
371
|
-
| `kilo/tencent/hy3` | 262K | | | | | | $0.
|
|
372
|
+
| `kilo/tencent/hy3` | 262K | | | | | | $0.13 | $0.53 |
|
|
372
373
|
| `kilo/tencent/hy3-preview` | 262K | | | | | | $0.18 | $0.60 |
|
|
373
374
|
| `kilo/tencent/hy4-preview` | 1.0M | | | | | | $0.83 | $3 |
|
|
374
375
|
| `kilo/thedrummer/cydonia-24b-v4.1` | 131K | | | | | | $0.30 | $0.50 |
|
|
375
376
|
| `kilo/thedrummer/skyfall-36b-v2` | 33K | | | | | | $0.55 | $0.80 |
|
|
376
377
|
| `kilo/thedrummer/unslopnemo-12b` | 1.0M | | | | | | $0.40 | $0.40 |
|
|
377
|
-
| `kilo/thinkingmachines/inkling` |
|
|
378
|
+
| `kilo/thinkingmachines/inkling` | 1.0M | | | | | | $0.95 | $4 |
|
|
378
379
|
| `kilo/thinkingmachines/inkling-small` | 524K | | | | | | $0.45 | $1 |
|
|
379
380
|
| `kilo/thinkingmachines/inkling-small:free` | 1.0M | | | | | | — | — |
|
|
380
381
|
| `kilo/thinkingmachines/inkling:free` | 1.0M | | | | | | — | — |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# LLM Gateway
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 371 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [LLM Gateway documentation](https://llmgateway.io/docs).
|
|
10
10
|
|
|
@@ -183,9 +183,8 @@ for await (const chunk of stream) {
|
|
|
183
183
|
| `llmgateway-providers/deepinfra/qwen3-vl-235b-a22b-instruct` | 262K | | | | | | $0.20 | $0.88 |
|
|
184
184
|
| `llmgateway-providers/deepinfra/qwen3-vl-30b-a3b-instruct` | 262K | | | | | | $0.15 | $0.60 |
|
|
185
185
|
| `llmgateway-providers/deepinfra/qwen3.5-9b` | 262K | | | | | | $0.10 | $0.15 |
|
|
186
|
-
| `llmgateway-providers/deepseek/deepseek-v4-flash` | 1.1M | | | | | | $0.14 | $0.28 |
|
|
187
|
-
| `llmgateway-providers/deepseek/deepseek-v4-flash-vision-exp` | 1.1M | | | | | | $0.14 | $0.28 |
|
|
188
186
|
| `llmgateway-providers/deepseek/deepseek-v4-pro` | 1.1M | | | | | | $0.43 | $0.87 |
|
|
187
|
+
| `llmgateway-providers/deepseek/deepseek-v4.1-flash` | 1.1M | | | | | | $0.15 | $0.60 |
|
|
189
188
|
| `llmgateway-providers/embercloud/glm-4.5` | 131K | | | | | | $0.60 | $2 |
|
|
190
189
|
| `llmgateway-providers/embercloud/glm-4.5-air` | 131K | | | | | | $0.13 | $0.85 |
|
|
191
190
|
| `llmgateway-providers/embercloud/glm-4.7` | 200K | | | | | | $0.38 | $2 |
|
|
@@ -57,8 +57,8 @@ for await (const chunk of stream) {
|
|
|
57
57
|
| `llmgateway/custom` | 128K | | | | | | — | — |
|
|
58
58
|
| `llmgateway/deepseek-v3.2` | 164K | | | | | | $0.26 | $0.38 |
|
|
59
59
|
| `llmgateway/deepseek-v4-flash` | 1.1M | | | | | | $0.05 | $0.10 |
|
|
60
|
-
| `llmgateway/deepseek-v4-flash-vision-exp` | 1.1M | | | | | | $0.14 | $0.28 |
|
|
61
60
|
| `llmgateway/deepseek-v4-pro` | 1.1M | | | | | | $0.43 | $0.87 |
|
|
61
|
+
| `llmgateway/deepseek-v4.1-flash` | 1.1M | | | | | | $0.15 | $0.60 |
|
|
62
62
|
| `llmgateway/ernie-4.5-vl-424b-a47b` | 123K | | | | | | $0.42 | $1 |
|
|
63
63
|
| `llmgateway/fugu-ultra` | 1.0M | | | | | | $5 | $30 |
|
|
64
64
|
| `llmgateway/gemini-2.5-flash` | 1.0M | | | | | | $0.30 | $3 |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# NanoGPT
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 587 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [NanoGPT documentation](https://docs.nano-gpt.com).
|
|
10
10
|
|
|
@@ -50,7 +50,7 @@ for await (const chunk of stream) {
|
|
|
50
50
|
| `nano-gpt/alibaba/qwen3.6-27b` | 260K | | | | | | $0.20 | $2 |
|
|
51
51
|
| `nano-gpt/alibaba/qwen3.6-27b:thinking` | 260K | | | | | | $0.20 | $2 |
|
|
52
52
|
| `nano-gpt/alibaba/qwen3.6-flash` | 992K | | | | | | $0.19 | $1 |
|
|
53
|
-
| `nano-gpt/alibaba/qwen3.8-flash` | 992K | | | | | | $0.
|
|
53
|
+
| `nano-gpt/alibaba/qwen3.8-flash` | 992K | | | | | | $0.14 | $0.42 |
|
|
54
54
|
| `nano-gpt/alibaba/qwen3.8-max-0902` | 992K | | | | | | $2 | $6 |
|
|
55
55
|
| `nano-gpt/amazon/nova-2-lite-v1` | 1.0M | | | | | | $0.51 | $4 |
|
|
56
56
|
| `nano-gpt/amazon/nova-lite-v1` | 300K | | | | | | $0.06 | $0.24 |
|
|
@@ -203,8 +203,8 @@ for await (const chunk of stream) {
|
|
|
203
203
|
| `nano-gpt/gemini-3-pro-image-preview` | 66K | | | | | | $2 | $12 |
|
|
204
204
|
| `nano-gpt/gemini-exp-1206` | 2.1M | | | | | | $1 | $5 |
|
|
205
205
|
| `nano-gpt/gemma-4-12b-it` | 262K | | | | | | $0.05 | $0.25 |
|
|
206
|
-
| `nano-gpt/gemma-4-12b-it-semancer` |
|
|
207
|
-
| `nano-gpt/gemma-4-12b-it-station-keeper` |
|
|
206
|
+
| `nano-gpt/gemma-4-12b-it-semancer` | 262K | | | | | | $0.05 | $0.25 |
|
|
207
|
+
| `nano-gpt/gemma-4-12b-it-station-keeper` | 262K | | | | | | $0.05 | $0.25 |
|
|
208
208
|
| `nano-gpt/gemma-4-26b-a4b-it-chimerax` | 262K | | | | | | $0.12 | $0.38 |
|
|
209
209
|
| `nano-gpt/gemma-4-26b-a4b-it-darksoul` | 262K | | | | | | $0.12 | $0.38 |
|
|
210
210
|
| `nano-gpt/gemma-4-26b-a4b-it-luminous` | 262K | | | | | | $0.12 | $0.38 |
|
|
@@ -416,8 +416,6 @@ for await (const chunk of stream) {
|
|
|
416
416
|
| `nano-gpt/openai/o4-mini-high` | 200K | | | | | | $1 | $4 |
|
|
417
417
|
| `nano-gpt/ornith-ai/ornith-1.5-35b-a3b` | 262K | | | | | | $0.10 | $0.40 |
|
|
418
418
|
| `nano-gpt/ornith-ai/ornith-1.5-35b-a3b:thinking` | 262K | | | | | | $0.10 | $0.40 |
|
|
419
|
-
| `nano-gpt/ornith-ai/ornith-1.5-9b` | 262K | | | | | | $0.10 | $0.20 |
|
|
420
|
-
| `nano-gpt/ornith-ai/ornith-1.5-9b:thinking` | 262K | | | | | | $0.10 | $0.20 |
|
|
421
419
|
| `nano-gpt/pamanseau/OpenReasoning-Nemotron-32B` | 33K | | | | | | $0.10 | $0.40 |
|
|
422
420
|
| `nano-gpt/perceptron/perceptron-mk1` | 33K | | | | | | $0.15 | $2 |
|
|
423
421
|
| `nano-gpt/perplexity-academic-researcher` | 128K | | | | | | $2 | $8 |
|
|
@@ -455,8 +453,6 @@ for await (const chunk of stream) {
|
|
|
455
453
|
| `nano-gpt/qwen/qwen3.5-plus` | 984K | | | | | | $0.40 | $2 |
|
|
456
454
|
| `nano-gpt/qwen/qwen3.5-plus-thinking` | 984K | | | | | | $0.40 | $2 |
|
|
457
455
|
| `nano-gpt/qwen/Qwen3.6-35B-A3B` | 262K | | | | | | $0.11 | $0.80 |
|
|
458
|
-
| `nano-gpt/qwen/qwen3.6-35b-a3b-uncensored` | 262K | | | | | | $0.15 | $0.95 |
|
|
459
|
-
| `nano-gpt/qwen/qwen3.6-35b-a3b-uncensored:thinking` | 262K | | | | | | $0.15 | $0.95 |
|
|
460
456
|
| `nano-gpt/qwen/Qwen3.6-35B-A3B:thinking` | 262K | | | | | | $0.11 | $0.80 |
|
|
461
457
|
| `nano-gpt/qwen/qwen3.8-2.4t-a95b` | 991K | | | | | | $2 | $6 |
|
|
462
458
|
| `nano-gpt/qwen/qwen3.8-27b-fable` | 262K | | | | | | $0.25 | $2 |
|
|
@@ -149,9 +149,9 @@ for await (const chunk of stream) {
|
|
|
149
149
|
| `ofox/z-ai/glm-5` | 205K | | | | | | $1 | $3 |
|
|
150
150
|
| `ofox/z-ai/glm-5-turbo` | 200K | | | | | | $1 | $4 |
|
|
151
151
|
| `ofox/z-ai/glm-5.1` | 200K | | | | | | $1 | $4 |
|
|
152
|
-
| `ofox/z-ai/glm-5.2` | 1.0M | | | | | | $
|
|
152
|
+
| `ofox/z-ai/glm-5.2` | 1.0M | | | | | | $1 | $4 |
|
|
153
153
|
| `ofox/z-ai/glm-5.3` | 1.0M | | | | | | $1 | $4 |
|
|
154
|
-
| `ofox/z-ai/glm-5.3-flash` | 1.0M | | | | | | $0.
|
|
154
|
+
| `ofox/z-ai/glm-5.3-flash` | 1.0M | | | | | | $0.15 | $0.50 |
|
|
155
155
|
| `ofox/z-ai/glm-5v-turbo` | 200K | | | | | | $1 | $4 |
|
|
156
156
|
|
|
157
157
|
Model availability, capabilities, context windows, and pricing are sourced from [models.dev](https://models.dev) and may change.
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# OpenCode Go
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 36 OpenCode Go models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [OpenCode Go documentation](https://opencode.ai/docs/zen).
|
|
10
10
|
|
|
@@ -19,7 +19,7 @@ const agent = new Agent({
|
|
|
19
19
|
id: "my-agent",
|
|
20
20
|
name: "My Agent",
|
|
21
21
|
instructions: "You are a helpful assistant",
|
|
22
|
-
model: "opencode-go/deepseek-
|
|
22
|
+
model: "opencode-go/deepseek-flash"
|
|
23
23
|
});
|
|
24
24
|
|
|
25
25
|
// Generate a response
|
|
@@ -38,8 +38,9 @@ for await (const chunk of stream) {
|
|
|
38
38
|
|
|
39
39
|
| Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
|
|
40
40
|
| ------------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
|
|
41
|
-
| `opencode-go/deepseek-
|
|
42
|
-
| `opencode-go/deepseek-v4-flash
|
|
41
|
+
| `opencode-go/deepseek-flash` | 1.0M | | | | | | $0.15 | $0.60 |
|
|
42
|
+
| `opencode-go/deepseek-v4-flash` | 1.0M | | | | | | $0.15 | $0.60 |
|
|
43
|
+
| `opencode-go/deepseek-v4-flash-vision-exp` | 1.0M | | | | | | $0.15 | $0.60 |
|
|
43
44
|
| `opencode-go/deepseek-v4-pro` | 1.0M | | | | | | $0.66 | $2 |
|
|
44
45
|
| `opencode-go/glm-5.1` | 203K | | | | | | $1 | $4 |
|
|
45
46
|
| `opencode-go/glm-5.2` | 1.0M | | | | | | $1 | $4 |
|
|
@@ -59,7 +60,6 @@ for await (const chunk of stream) {
|
|
|
59
60
|
| `opencode-go/minimax-m3` | 1.0M | | | | | | $0.30 | $1 |
|
|
60
61
|
| `opencode-go/muse-spark-1.2-contributor` | 1.0M | | | | | | $0.10 | $0.20 |
|
|
61
62
|
| `opencode-go/muse-spark-1.3-contributor` | 1.0M | | | | | | $0.10 | $0.20 |
|
|
62
|
-
| `opencode-go/omen-alpha` | 500K | | | | | | $0.20 | $0.66 |
|
|
63
63
|
| `opencode-go/qwen3.6-plus` | 1.0M | | | | | | $0.50 | $3 |
|
|
64
64
|
| `opencode-go/qwen3.7-max` | 1.0M | | | | | | $3 | $8 |
|
|
65
65
|
| `opencode-go/qwen3.7-plus` | 1.0M | | | | | | $0.40 | $2 |
|
|
@@ -78,7 +78,7 @@ const agent = new Agent({
|
|
|
78
78
|
name: "custom-agent",
|
|
79
79
|
model: {
|
|
80
80
|
url: "https://opencode.ai/zen/go/v1",
|
|
81
|
-
id: "opencode-go/deepseek-
|
|
81
|
+
id: "opencode-go/deepseek-flash",
|
|
82
82
|
apiKey: process.env.OPENCODE_API_KEY,
|
|
83
83
|
headers: {
|
|
84
84
|
"X-Custom-Header": "value"
|
|
@@ -97,7 +97,7 @@ const agent = new Agent({
|
|
|
97
97
|
const useAdvanced = requestContext.task === "complex";
|
|
98
98
|
return useAdvanced
|
|
99
99
|
? "opencode-go/qwen3.8-max"
|
|
100
|
-
: "opencode-go/deepseek-
|
|
100
|
+
: "opencode-go/deepseek-flash";
|
|
101
101
|
}
|
|
102
102
|
});
|
|
103
103
|
```
|
|
@@ -23,6 +23,24 @@ const { mastra, controller } = await mountAgentControllerOnMastra({
|
|
|
23
23
|
const session = await controller.createSession({ resourceId: 'user-123' })
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
+
## Commit attribution
|
|
27
|
+
|
|
28
|
+
Use `coAuthor` to set the `Co-Authored-By` trailer in coding-agent commit guidance:
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
const { mastra, controller } = await mountAgentControllerOnMastra({
|
|
32
|
+
cwd: process.cwd(),
|
|
33
|
+
coAuthor: {
|
|
34
|
+
name: 'my-coding-app',
|
|
35
|
+
email: 'my-coding-app@example.com',
|
|
36
|
+
},
|
|
37
|
+
})
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Both fields are optional. An omitted field uses the SDK default: `mastra-platform[bot]` for the name and `284800079+mastra-platform[bot]@users.noreply.github.com` for the email.
|
|
41
|
+
|
|
42
|
+
The `mastracode` terminal app sets its name to `mastracode`, and Factory sets its name to `mastra-platform[bot]`. Both use the same default email, so GitHub resolves their trailers to the same bot account while the raw commit message retains the app name.
|
|
43
|
+
|
|
26
44
|
Pass an existing `mastra` to mount the controller onto a Mastra instance that already hosts other primitives:
|
|
27
45
|
|
|
28
46
|
```typescript
|
|
@@ -38,6 +56,8 @@ const { controller } = await mountAgentControllerOnMastra({ mastra })
|
|
|
38
56
|
|
|
39
57
|
**cwd** (`string`): Working directory for project detection. (Default: `process.cwd()`)
|
|
40
58
|
|
|
59
|
+
**coAuthor** (`{ name?: string; email?: string }`): Commit co-author identity included in coding-agent commit guidance. Omitted fields use the SDK defaults.
|
|
60
|
+
|
|
41
61
|
**mastra** (`Mastra`): Existing Mastra instance to mount onto. When omitted, a Mastra is created that owns the controller storage.
|
|
42
62
|
|
|
43
63
|
**controllerId** (`string`): Id under which the controller is registered on the Mastra instance.
|
|
@@ -58,7 +58,7 @@ const prompt = buildBasePrompt({
|
|
|
58
58
|
|
|
59
59
|
**mode** (`string`): Active agent mode (for example, "build" or "plan").
|
|
60
60
|
|
|
61
|
-
**modelId** (`string`): Identifier of the active model.
|
|
61
|
+
**modelId** (`string`): Identifier of the active model. It is not included in the commit Co-Authored-By line.
|
|
62
62
|
|
|
63
63
|
**activePlan** (`{ title: string; plan: string; approvedAt: string } | null`): The currently approved plan, if any.
|
|
64
64
|
|
|
@@ -10,7 +10,7 @@ Mastra v1 was released in January 2026. We recommend starting any new projects w
|
|
|
10
10
|
|
|
11
11
|
This guide covers the breaking changes when upgrading from Mastra 0.x to v1.0. The migration is organized by package and feature area to help you systematically update your codebase.
|
|
12
12
|
|
|
13
|
-
> **Need help?:** Need help with the migration? Join our [Discord community](https://discord.gg/
|
|
13
|
+
> **Need help?:** Need help with the migration? Join our [Discord community](https://discord.gg/mastra-ai) to ask questions.
|
|
14
14
|
|
|
15
15
|
> **Coming from Mastra Cloud?:** The legacy Mastra Cloud product has been replaced by the [Mastra platform](https://mastra.ai/docs/mastra-platform/overview), which splits hosting into two separate products: **Studio** (visual environment, observability) and **Server** (production API). Because old Mastra Cloud access tokens don't work with Mastra platform, create new ones with `mastra auth tokens create`.
|
|
16
16
|
>
|
|
@@ -53,7 +53,7 @@ For ClickHouse vNext, the method records the complete predicate and waits for li
|
|
|
53
53
|
|
|
54
54
|
### `SpanTypeMap`
|
|
55
55
|
|
|
56
|
-
Mapping of span types to their corresponding attribute interfaces.
|
|
56
|
+
Mapping of span types to their corresponding attribute interfaces. The list below is abbreviated. The `SpanTypeMap` interface in `@mastra/core/observability` is the complete one.
|
|
57
57
|
|
|
58
58
|
```typescript
|
|
59
59
|
interface SpanTypeMap {
|
|
@@ -61,6 +61,7 @@ interface SpanTypeMap {
|
|
|
61
61
|
WORKFLOW_RUN: WorkflowRunAttributes
|
|
62
62
|
MODEL_GENERATION: ModelGenerationAttributes
|
|
63
63
|
MODEL_STEP: ModelStepAttributes
|
|
64
|
+
MODEL_INFERENCE: ModelInferenceAttributes
|
|
64
65
|
MODEL_CHUNK: ModelChunkAttributes
|
|
65
66
|
TOOL_CALL: ToolCallAttributes
|
|
66
67
|
CLIENT_TOOL_CALL: ClientToolCallAttributes
|
|
@@ -85,6 +86,70 @@ interface SpanTypeMap {
|
|
|
85
86
|
|
|
86
87
|
This mapping defines which attribute interface is used for each span type when creating or processing spans.
|
|
87
88
|
|
|
89
|
+
### `SpanInputMap` and `SpanOutputMap`
|
|
90
|
+
|
|
91
|
+
Mapping of the span types whose `input` and `output` Mastra writes itself with a fixed shape. Every other span type keeps `any`: tool arguments and workflow data are caller-defined, `MODEL_CHUNK` carries several chunk shapes on one span type, and `GENERIC` is the escape hatch for custom spans.
|
|
92
|
+
|
|
93
|
+
```typescript
|
|
94
|
+
interface SpanInputMap {
|
|
95
|
+
AGENT_RUN: AgentRunInput
|
|
96
|
+
MODEL_GENERATION: ModelGenerationInput
|
|
97
|
+
MODEL_STEP: ModelStepInput
|
|
98
|
+
MODEL_INFERENCE: ModelStepInput
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
interface SpanOutputMap {
|
|
102
|
+
AGENT_RUN: AgentRunOutput
|
|
103
|
+
MODEL_GENERATION: ModelGenerationOutput
|
|
104
|
+
MODEL_STEP: ModelStepOutput
|
|
105
|
+
MODEL_INFERENCE: ModelStepResult
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** The mapped shape when the map lists the type, otherwise `any` */
|
|
109
|
+
type SpanInput<TType extends SpanType> = TType extends keyof SpanInputMap
|
|
110
|
+
? SpanInputMap[TType]
|
|
111
|
+
: any
|
|
112
|
+
type SpanOutput<TType extends SpanType> = TType extends keyof SpanOutputMap
|
|
113
|
+
? SpanOutputMap[TType]
|
|
114
|
+
: any
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Narrow a span by its type to read the typed payload. On a stored `SpanRecord`, use `isSpanRecordOfType`:
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
import { SpanType, isSpanRecordOfType } from '@mastra/core/observability'
|
|
121
|
+
|
|
122
|
+
if (isSpanRecordOfType(span, SpanType.MODEL_GENERATION)) {
|
|
123
|
+
span.input?.messages // MessageListInput
|
|
124
|
+
span.attributes?.usage // UsageStats | undefined
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
To pick a renderer without checking shapes yourself, describe the payload. The tag is derived at read time from `spanType` and the value's shape. Nothing is stored.
|
|
129
|
+
|
|
130
|
+
```typescript
|
|
131
|
+
import {
|
|
132
|
+
describeSpanError,
|
|
133
|
+
describeSpanInput,
|
|
134
|
+
describeSpanOutput,
|
|
135
|
+
} from '@mastra/core/observability'
|
|
136
|
+
|
|
137
|
+
const input = describeSpanInput(span)
|
|
138
|
+
// { type: 'text' | 'messages' | 'agent-run-resume' | 'json'; value } | undefined
|
|
139
|
+
|
|
140
|
+
const output = describeSpanOutput(span)
|
|
141
|
+
// { type: 'interrupted' | 'agent-run-result' | 'model-generation-result' | 'model-step-result' | 'text' | 'json'; value } | undefined
|
|
142
|
+
|
|
143
|
+
switch (output?.type) {
|
|
144
|
+
case 'interrupted':
|
|
145
|
+
return output.value.status // 'suspended' | 'aborted'
|
|
146
|
+
case 'model-generation-result':
|
|
147
|
+
return output.value.text
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
describeSpanError(span) // SpanErrorInfo | undefined
|
|
151
|
+
```
|
|
152
|
+
|
|
88
153
|
### Span
|
|
89
154
|
|
|
90
155
|
Span interface, used internally for tracing.
|
|
@@ -107,8 +172,8 @@ interface Span<TType extends SpanType> {
|
|
|
107
172
|
|
|
108
173
|
attributes?: SpanTypeMap[TType]
|
|
109
174
|
metadata?: Record<string, any>
|
|
110
|
-
input?:
|
|
111
|
-
output?:
|
|
175
|
+
input?: SpanInput<TType>
|
|
176
|
+
output?: SpanOutput<TType>
|
|
112
177
|
errorInfo?: any
|
|
113
178
|
|
|
114
179
|
/** Tags for categorizing traces (only present on root spans) */
|
|
@@ -298,7 +363,7 @@ interface SpanOutputProcessor {
|
|
|
298
363
|
|
|
299
364
|
### `SpanType`
|
|
300
365
|
|
|
301
|
-
AI-specific span types with their associated metadata.
|
|
366
|
+
AI-specific span types with their associated metadata. The list below is abbreviated. The `SpanType` enum in `@mastra/core/observability` is the complete one.
|
|
302
367
|
|
|
303
368
|
```typescript
|
|
304
369
|
enum SpanType {
|
|
@@ -314,6 +379,9 @@ enum SpanType {
|
|
|
314
379
|
/** Single model execution step within a generation (one API call) */
|
|
315
380
|
MODEL_STEP = 'model_step',
|
|
316
381
|
|
|
382
|
+
/** Model provider call within a step - wraps only the inference, excluding processors and tool executions */
|
|
383
|
+
MODEL_INFERENCE = 'model_inference',
|
|
384
|
+
|
|
317
385
|
/** Individual model streaming chunk/event */
|
|
318
386
|
MODEL_CHUNK = 'model_chunk',
|
|
319
387
|
|
|
@@ -627,6 +695,125 @@ interface WorkflowStepAttributes {
|
|
|
627
695
|
}
|
|
628
696
|
```
|
|
629
697
|
|
|
698
|
+
## Span payloads
|
|
699
|
+
|
|
700
|
+
### `AgentRunInput`
|
|
701
|
+
|
|
702
|
+
Input recorded on `AGENT_RUN` spans: the messages the caller passed for a fresh run, or the resume data for a resumed run.
|
|
703
|
+
|
|
704
|
+
```typescript
|
|
705
|
+
type AgentRunInput = MessageListInput | { messages: MessageListInput } | AgentRunResumeInput
|
|
706
|
+
|
|
707
|
+
interface AgentRunResumeInput {
|
|
708
|
+
/** Resume data, kept nested when it names a different tool than the suspended one */
|
|
709
|
+
resumeData?: unknown
|
|
710
|
+
/** Tool the run resumes into */
|
|
711
|
+
toolName?: string
|
|
712
|
+
/** Tool call the run resumes into */
|
|
713
|
+
toolCallId?: string
|
|
714
|
+
[key: string]: unknown
|
|
715
|
+
}
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
### `AgentRunOutput`
|
|
719
|
+
|
|
720
|
+
Output recorded on `AGENT_RUN` spans.
|
|
721
|
+
|
|
722
|
+
```typescript
|
|
723
|
+
type AgentRunOutput = AgentRunResult | InterruptedSpanOutput
|
|
724
|
+
|
|
725
|
+
interface AgentRunResult {
|
|
726
|
+
/** Final response text */
|
|
727
|
+
text?: string
|
|
728
|
+
/** Final structured output */
|
|
729
|
+
object?: unknown
|
|
730
|
+
/** Generated files */
|
|
731
|
+
files?: unknown[]
|
|
732
|
+
/** Tripwire that aborted the run */
|
|
733
|
+
tripwire?: StepTripwireData
|
|
734
|
+
}
|
|
735
|
+
```
|
|
736
|
+
|
|
737
|
+
### `ModelGenerationInput`
|
|
738
|
+
|
|
739
|
+
Input recorded on `MODEL_GENERATION` spans.
|
|
740
|
+
|
|
741
|
+
Mastra's own loop records the normalized model messages, system messages first. SDK agents record the raw messages the caller passed, so `messages` keeps the full `MessageListInput` shape.
|
|
742
|
+
|
|
743
|
+
```typescript
|
|
744
|
+
interface ModelGenerationInput {
|
|
745
|
+
/** Messages sent to the model */
|
|
746
|
+
messages: MessageListInput
|
|
747
|
+
/** Output schema, when structured output was requested */
|
|
748
|
+
schema?: unknown
|
|
749
|
+
}
|
|
750
|
+
```
|
|
751
|
+
|
|
752
|
+
### `ModelGenerationOutput`
|
|
753
|
+
|
|
754
|
+
Output recorded on `MODEL_GENERATION` spans: a `ModelGenerationResult` when the generation finishes, or an `InterruptedSpanOutput` when the run stops first. Every field of `ModelGenerationResult` is optional: a durable run records only `text`.
|
|
755
|
+
|
|
756
|
+
```typescript
|
|
757
|
+
type ModelGenerationOutput = ModelGenerationResult | InterruptedSpanOutput
|
|
758
|
+
|
|
759
|
+
interface ModelGenerationResult {
|
|
760
|
+
text?: string
|
|
761
|
+
object?: unknown
|
|
762
|
+
reasoning?: unknown
|
|
763
|
+
reasoningText?: string
|
|
764
|
+
files?: unknown[]
|
|
765
|
+
sources?: unknown[]
|
|
766
|
+
toolCalls?: unknown[]
|
|
767
|
+
warnings?: unknown[]
|
|
768
|
+
}
|
|
769
|
+
```
|
|
770
|
+
|
|
771
|
+
### `ModelStepInput`
|
|
772
|
+
|
|
773
|
+
Input recorded on `MODEL_STEP` and `MODEL_INFERENCE` spans: a shallow preview of what the step sent to the model.
|
|
774
|
+
|
|
775
|
+
```typescript
|
|
776
|
+
type ModelStepInput = ModelStepMessage[] | Record<string, unknown> | string
|
|
777
|
+
|
|
778
|
+
interface ModelStepMessage {
|
|
779
|
+
/** Message role (e.g., 'system', 'user', 'assistant', 'tool') */
|
|
780
|
+
role: string
|
|
781
|
+
/** Message text, with non-text parts summarized */
|
|
782
|
+
content: string
|
|
783
|
+
}
|
|
784
|
+
```
|
|
785
|
+
|
|
786
|
+
### `ModelStepOutput`
|
|
787
|
+
|
|
788
|
+
Output recorded on `MODEL_STEP` spans. A finished step records a `ModelStepResult`, which is the step output without `usage` (that lives on the attributes). A step cut short by a suspension or an abort records an `InterruptedSpanOutput` instead. `MODEL_INFERENCE` spans always record a `ModelStepResult`.
|
|
789
|
+
|
|
790
|
+
```typescript
|
|
791
|
+
type ModelStepOutput = ModelStepResult | InterruptedSpanOutput
|
|
792
|
+
|
|
793
|
+
interface ModelStepResult {
|
|
794
|
+
text?: string
|
|
795
|
+
toolCalls?: unknown[]
|
|
796
|
+
steps?: unknown[]
|
|
797
|
+
object?: unknown
|
|
798
|
+
}
|
|
799
|
+
```
|
|
800
|
+
|
|
801
|
+
### `InterruptedSpanOutput`
|
|
802
|
+
|
|
803
|
+
Output recorded on `AGENT_RUN`, `MODEL_GENERATION` and `MODEL_STEP` spans when the run stops before the span's own result exists: a durable run suspended, or the caller aborted. `MODEL_INFERENCE` spans never carry it.
|
|
804
|
+
|
|
805
|
+
```typescript
|
|
806
|
+
interface InterruptedSpanOutput {
|
|
807
|
+
status: 'suspended' | 'aborted'
|
|
808
|
+
/** Why the run stopped */
|
|
809
|
+
reason?: string
|
|
810
|
+
/** Tool that suspended the run */
|
|
811
|
+
toolName?: string
|
|
812
|
+
/** Tool call that suspended the run */
|
|
813
|
+
toolCallId?: string
|
|
814
|
+
}
|
|
815
|
+
```
|
|
816
|
+
|
|
630
817
|
## Options types
|
|
631
818
|
|
|
632
819
|
### `StartSpanOptions`
|
|
@@ -648,7 +835,7 @@ interface StartSpanOptions<TType extends SpanType> {
|
|
|
648
835
|
metadata?: Record<string, any>
|
|
649
836
|
|
|
650
837
|
/** Input data */
|
|
651
|
-
input?:
|
|
838
|
+
input?: SpanInput<TType>
|
|
652
839
|
|
|
653
840
|
/** Parent span */
|
|
654
841
|
parent?: AnySpan
|
|
@@ -674,10 +861,10 @@ interface UpdateSpanOptions<TType extends SpanType> {
|
|
|
674
861
|
metadata?: Record<string, any>
|
|
675
862
|
|
|
676
863
|
/** Input data */
|
|
677
|
-
input?:
|
|
864
|
+
input?: SpanInput<TType>
|
|
678
865
|
|
|
679
866
|
/** Output data */
|
|
680
|
-
output?:
|
|
867
|
+
output?: SpanOutput<TType>
|
|
681
868
|
}
|
|
682
869
|
```
|
|
683
870
|
|
|
@@ -688,7 +875,7 @@ Options for ending spans.
|
|
|
688
875
|
```typescript
|
|
689
876
|
interface EndSpanOptions<TType extends SpanType> {
|
|
690
877
|
/** Output data */
|
|
691
|
-
output?:
|
|
878
|
+
output?: SpanOutput<TType>
|
|
692
879
|
|
|
693
880
|
/** Span metadata */
|
|
694
881
|
metadata?: Record<string, any>
|
|
@@ -35,10 +35,10 @@ interface BaseSpan<TType extends SpanType> {
|
|
|
35
35
|
metadata?: Record<string, any>
|
|
36
36
|
|
|
37
37
|
/** Input passed at the start of the span */
|
|
38
|
-
input?:
|
|
38
|
+
input?: SpanInput<TType>
|
|
39
39
|
|
|
40
40
|
/** Output generated at the end of the span */
|
|
41
|
-
output?:
|
|
41
|
+
output?: SpanOutput<TType>
|
|
42
42
|
|
|
43
43
|
/** Error information if span failed */
|
|
44
44
|
errorInfo?: {
|
|
@@ -111,6 +111,9 @@ Hono and Fastify enforce the request-body limit before JSON parsing. Express and
|
|
|
111
111
|
| Score | `scorerId`, `scorerVersion`, `scoreSource`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists` |
|
|
112
112
|
| Score | `score`, `timestamp` | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
|
|
113
113
|
| Score | `spanId` | `exists`, `notExists` |
|
|
114
|
+
| Feedback | `feedbackType`, `feedbackSource`, `feedbackUserId`, `sourceId`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists` |
|
|
115
|
+
| Feedback | `value`, `timestamp` | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
|
|
116
|
+
| Feedback | `comment` | `exists`, `notExists` |
|
|
114
117
|
|
|
115
118
|
Compose predicates with `{ op: 'and', args: [...] }`, `{ op: 'or', args: [...] }`, and `{ op: 'not', arg: ... }`. Comparison predicates place a field reference on the left and a literal on the right. Membership predicates use a field reference in `value` and a homogeneous literal array in `set`.
|
|
116
119
|
|
|
@@ -270,6 +273,45 @@ The key must name one top-level property. Empty keys and nested paths are reject
|
|
|
270
273
|
|
|
271
274
|
Metadata fields aren't available for grouping or field discovery.
|
|
272
275
|
|
|
276
|
+
### Filter by feedback
|
|
277
|
+
|
|
278
|
+
Every condition inside one `feedback.some` or `feedback.none` clause applies to the same current feedback record. `feedbackType` and `feedbackSource` are exact application-defined strings rather than built-in enums. This query finds traces with a numeric patient rating below zero:
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
const negativePatientRating = {
|
|
282
|
+
feedback: {
|
|
283
|
+
some: {
|
|
284
|
+
op: 'and',
|
|
285
|
+
args: [
|
|
286
|
+
{ op: 'eq', left: { path: 'feedbackType' }, right: { literal: 'rating' } },
|
|
287
|
+
{ op: 'eq', left: { path: 'feedbackSource' }, right: { literal: 'patient' } },
|
|
288
|
+
{ op: 'lt', left: { path: 'value' }, right: { literal: 0 } },
|
|
289
|
+
],
|
|
290
|
+
},
|
|
291
|
+
},
|
|
292
|
+
}
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Strict stored-value types are the portable contract for feedback predicates. PostgreSQL and ClickHouse distinguish numeric `3` from textual `'3'` for equality and ordered comparisons. DuckDB currently persists feedback values as `VARCHAR`, so numeric-looking strings may be coerced for equality and ordered numeric predicates. OBS-306 will remove this DuckDB exception through typed persistence. Ordered operators require a finite numeric literal. `eq` and `ne` accept one string or number, while `in` and `notIn` require a non-empty set containing only strings or only numbers. `exists` and `notExists` test for either value type.
|
|
296
|
+
|
|
297
|
+
Use `none` to select traces without a matching record. Traces with no feedback also match:
|
|
298
|
+
|
|
299
|
+
```typescript
|
|
300
|
+
const missingClinicianReview = {
|
|
301
|
+
feedback: {
|
|
302
|
+
none: {
|
|
303
|
+
op: 'and',
|
|
304
|
+
args: [
|
|
305
|
+
{ op: 'eq', left: { path: 'feedbackType' }, right: { literal: 'clinical-review' } },
|
|
306
|
+
{ op: 'eq', left: { path: 'feedbackSource' }, right: { literal: 'clinician' } },
|
|
307
|
+
],
|
|
308
|
+
},
|
|
309
|
+
},
|
|
310
|
+
}
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
Feedback `timestamp` predicates are independent of the root `timeRange`. Use `comment` only with `exists` or `notExists`. Comment contents aren't searchable. The deprecated feedback fields `source` and `userId` aren't available. Use `feedbackSource` and `feedbackUserId`.
|
|
314
|
+
|
|
273
315
|
## Responses
|
|
274
316
|
|
|
275
317
|
An ungrouped query returns only lightweight completed traces:
|
|
@@ -13,27 +13,14 @@ import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
|
|
|
13
13
|
import Speaker from '@mastra/node-speaker'
|
|
14
14
|
|
|
15
15
|
const speaker = new Speaker({
|
|
16
|
-
sampleRate:
|
|
17
|
-
channels: 1,
|
|
18
|
-
bitDepth: 16,
|
|
16
|
+
sampleRate: 24000,
|
|
17
|
+
channels: 1,
|
|
18
|
+
bitDepth: 16,
|
|
19
19
|
})
|
|
20
20
|
|
|
21
|
-
// Initialize a real-time voice provider
|
|
22
21
|
const voice = new OpenAIRealtimeVoice({
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
apiKey: process.env.OPENAI_API_KEY,
|
|
26
|
-
options: {
|
|
27
|
-
sessionConfig: {
|
|
28
|
-
turn_detection: {
|
|
29
|
-
type: 'server_vad',
|
|
30
|
-
threshold: 0.6,
|
|
31
|
-
silence_duration_ms: 1200,
|
|
32
|
-
},
|
|
33
|
-
},
|
|
34
|
-
},
|
|
35
|
-
},
|
|
36
|
-
speaker: 'alloy', // Default voice
|
|
22
|
+
apiKey: process.env.OPENAI_API_KEY,
|
|
23
|
+
speaker: 'alloy',
|
|
37
24
|
})
|
|
38
25
|
// Connect to the real-time service
|
|
39
26
|
await voice.connect()
|
|
@@ -41,11 +28,6 @@ await voice.connect()
|
|
|
41
28
|
voice.on('speaker', stream => {
|
|
42
29
|
stream.pipe(speaker)
|
|
43
30
|
})
|
|
44
|
-
// With connection options
|
|
45
|
-
await voice.connect({
|
|
46
|
-
timeout: 10000, // 10 seconds timeout
|
|
47
|
-
reconnect: true,
|
|
48
|
-
})
|
|
49
31
|
```
|
|
50
32
|
|
|
51
33
|
## Parameters
|
|
@@ -58,19 +40,46 @@ Returns a `Promise<void>` that resolves when the connection is successfully esta
|
|
|
58
40
|
|
|
59
41
|
## Provider-specific options
|
|
60
42
|
|
|
61
|
-
|
|
43
|
+
Connection configuration depends on the real-time voice provider.
|
|
62
44
|
|
|
63
45
|
### OpenAI Realtime
|
|
64
46
|
|
|
65
|
-
|
|
47
|
+
`connect()` accepts an optional `requestContext` for tool execution:
|
|
48
|
+
|
|
49
|
+
**options.requestContext** (`RequestContext`): Runtime context passed to tools called during the session.
|
|
50
|
+
|
|
51
|
+
See [Request context](https://mastra.ai/docs/server/request-context) for how to populate runtime values.
|
|
52
|
+
|
|
53
|
+
Set `connectTimeoutMs` in the `OpenAIRealtimeVoice` constructor, not in the `connect()` call:
|
|
54
|
+
|
|
55
|
+
**connectTimeoutMs** (`number`): Connection handshake deadline in milliseconds. Must be a positive, finite number no greater than 2,147,483,647. Applies only to connection setup, not to an established session. (Default: `15000`)
|
|
56
|
+
|
|
57
|
+
## Connection failures
|
|
58
|
+
|
|
59
|
+
For OpenAI Realtime, `connect()` waits for both the WebSocket to open and the server to create a session. It rejects if the connection fails, the server reports an error during the handshake, or the socket closes before the session is ready. A silent handshake times out after 15,000 milliseconds by default.
|
|
60
|
+
|
|
61
|
+
Catch connection failures directly. An `error` event listener doesn't replace handling the rejected promise:
|
|
66
62
|
|
|
67
|
-
|
|
63
|
+
```typescript
|
|
64
|
+
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
|
|
65
|
+
|
|
66
|
+
const voice = new OpenAIRealtimeVoice({
|
|
67
|
+
apiKey: process.env.OPENAI_API_KEY,
|
|
68
|
+
connectTimeoutMs: 30_000,
|
|
69
|
+
})
|
|
70
|
+
|
|
71
|
+
try {
|
|
72
|
+
await voice.connect()
|
|
73
|
+
} catch (error) {
|
|
74
|
+
console.error('Could not connect to the realtime service:', error)
|
|
75
|
+
}
|
|
76
|
+
```
|
|
68
77
|
|
|
69
|
-
|
|
78
|
+
A failed handshake closes its socket and clears its pending waits. You can retry with `connect()` on the same instance.
|
|
70
79
|
|
|
71
80
|
## Using with `CompositeVoice`
|
|
72
81
|
|
|
73
|
-
When using `CompositeVoice`, the `connect()` method
|
|
82
|
+
When using `CompositeVoice`, the `connect()` method forwards its options to the configured real-time provider. It throws if no real-time provider is configured:
|
|
74
83
|
|
|
75
84
|
```typescript
|
|
76
85
|
import { CompositeVoice } from '@mastra/core/voice'
|
|
@@ -86,7 +95,7 @@ await voice.connect()
|
|
|
86
95
|
## Notes
|
|
87
96
|
|
|
88
97
|
- This method is only implemented by real-time voice providers that support speech-to-speech capabilities
|
|
89
|
-
-
|
|
98
|
+
- Providers that inherit the base `connect()` implementation log a debug message and resolve without establishing a connection
|
|
90
99
|
- The connection must be established before using other real-time methods like `send()` or `answer()`
|
|
91
100
|
- When you're done with the voice instance, call `close()` to properly clean up resources
|
|
92
101
|
- Some providers may automatically reconnect on connection loss, depending on their implementation
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "1.2.25-alpha.
|
|
3
|
+
"version": "1.2.25-alpha.8",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
"jsdom": "^26.1.0",
|
|
28
28
|
"local-pkg": "^1.1.2",
|
|
29
29
|
"zod": "^4.4.3",
|
|
30
|
-
"@mastra/core": "1.66.0-alpha.
|
|
30
|
+
"@mastra/core": "1.66.0-alpha.4",
|
|
31
31
|
"@mastra/mcp": "^1.17.3"
|
|
32
32
|
},
|
|
33
33
|
"devDependencies": {
|
|
@@ -45,8 +45,8 @@
|
|
|
45
45
|
"typescript": "^7.0.2",
|
|
46
46
|
"vitest": "4.1.10",
|
|
47
47
|
"@internal/lint": "0.0.131",
|
|
48
|
-
"@
|
|
49
|
-
"@
|
|
48
|
+
"@internal/types-builder": "0.0.106",
|
|
49
|
+
"@mastra/core": "1.66.0-alpha.4"
|
|
50
50
|
},
|
|
51
51
|
"homepage": "https://mastra.ai",
|
|
52
52
|
"repository": {
|