@mastra/mcp-docs-server 1.2.7-alpha.14 → 1.2.7-alpha.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/.docs/docs/agents/using-tools.md +2 -0
  2. package/.docs/docs/evals/datasets/overview.md +2 -0
  3. package/.docs/docs/evals/datasets/running-experiments.md +2 -0
  4. package/.docs/docs/evals/gates-and-verdicts.md +17 -0
  5. package/.docs/docs/getting-started/file-based-agents.md +7 -4
  6. package/.docs/docs/mastra-platform/github.md +2 -2
  7. package/.docs/docs/observability/logging.md +2 -0
  8. package/.docs/docs/observability/metrics/querying.md +2 -0
  9. package/.docs/docs/observability/tracing/overview.md +2 -0
  10. package/.docs/docs/workflows/overview.md +1 -1
  11. package/.docs/models/environment-variables.md +6 -2
  12. package/.docs/models/gateways/azure-openai.md +15 -15
  13. package/.docs/models/gateways/mastra.md +2 -2
  14. package/.docs/models/index.md +1 -1
  15. package/.docs/models/providers/crossmodel.md +4 -1
  16. package/.docs/models/providers/ebcloud.md +76 -0
  17. package/.docs/models/providers/lynkr.md +73 -0
  18. package/.docs/models/providers/stepfun-ai-step-plan.md +75 -0
  19. package/.docs/models/providers/stepfun-ai.md +6 -6
  20. package/.docs/models/providers/stepfun-step-plan.md +76 -0
  21. package/.docs/models/providers/stepfun.md +5 -5
  22. package/.docs/models/providers.md +6 -2
  23. package/.docs/reference/coding-agent/create-coding-agent.md +5 -4
  24. package/.docs/reference/evals/run-evals.md +2 -2
  25. package/.docs/reference/mastra-platform/api.md +1 -1
  26. package/.docs/reference/observability/metrics/automatic-metrics.md +8 -8
  27. package/.docs/reference/observability/tracing/exporters/braintrust.md +1 -0
  28. package/.docs/reference/observability/tracing/exporters/datadog.md +10 -9
  29. package/.docs/reference/observability/tracing/exporters/langsmith.md +8 -7
  30. package/.docs/reference/observability/tracing/exporters/posthog.md +13 -12
  31. package/.docs/reference/observability/tracing/exporters/sentry.md +1 -0
  32. package/.docs/reference/observability/tracing/interfaces.md +9 -0
  33. package/.docs/reference/processors/stream-error-retry-processor.md +25 -0
  34. package/.docs/reference/server/register-api-route.md +5 -4
  35. package/.docs/reference/templates/overview.md +1 -1
  36. package/CHANGELOG.md +7 -0
  37. package/package.json +5 -5
package/.docs/docs/agents/using-tools.md CHANGED
@@ -4,6 +4,8 @@
4
4
 
5
5
  Agents use tools to call APIs, query databases, or run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
6
6
 
7
+ **For AI agents:** Run `npx mastra api tool execute weather-tool '{"location":"San Francisco"}'` to test this tool directly instead of writing a temporary script. The command requires a running Mastra server; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api tool execute --schema` before constructing different input. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
8
+
7
9
  ## When to use tools
8
10
 
9
11
  Use tools when an agent needs additional context or information from remote resources, or when it needs to run code that performs a specific operation. This includes tasks a model can't reliably handle on its own, such as fetching live data or returning consistent, well-defined outputs.
package/.docs/docs/evals/datasets/overview.md CHANGED
@@ -6,6 +6,8 @@
6
6
 
7
7
  Datasets are collections of test cases that you run experiments against to measure how well your agents and workflows perform. Each mutation creates a new version, so you can reproduce past experiments exactly. Pair datasets with [scorers](https://mastra.ai/docs/evals/overview) to track quality across prompts, models, or code changes.
8
8
 
9
+ **For AI agents:** Run `npx mastra api dataset create '{"name":"translation-pairs"}'` to create a dataset directly instead of opening Studio or writing a temporary script. The command requires a running Mastra server with a storage adapter that supports datasets; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api dataset create --schema` before adding different dataset fields. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
10
+
9
11
  ## Usage
10
12
 
11
13
  ### Configure storage
package/.docs/docs/evals/datasets/running-experiments.md CHANGED
@@ -6,6 +6,8 @@
6
6
 
7
7
  An experiment runs every item in a dataset through a target (an agent, a workflow, or a scorer) and then optionally scores the outputs. Use a scorer as the target when you want to evaluate an LLM judge itself. Results are persisted to storage so you can compare runs across different prompts, models, or code changes.
8
8
 
9
+ **For AI agents:** Run `npx mastra api experiment run dataset_123 '{"name":"translation-baseline"}'` to start an experiment directly instead of opening Studio or writing a temporary script. Use a dataset ID returned by `npx mastra api dataset list` in place of the sample ID. The command requires a running Mastra server with dataset storage and registered experiment targets; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api experiment run --schema` before constructing different input, and get user approval before starting an experiment because it can make model calls. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
10
+
9
11
  ## Basic experiment
10
12
 
11
13
  Call [`startExperiment()`](https://mastra.ai/reference/datasets/startExperiment) with a target and scorers:
package/.docs/docs/evals/gates-and-verdicts.md CHANGED
@@ -66,6 +66,23 @@ const result = await runEvals({
66
66
 
67
67
  Any scorer works as a gate. Quick Checks are a natural fit because they return binary 1/0 scores. Visit [runEvals() reference](https://mastra.ai/reference/evals/run-evals) for the full parameter and return type documentation.
68
68
 
69
+ ### Gate-only runs
70
+
71
+ `scorers` is optional when at least one gate is provided. This is useful for deterministic CI checks where you only care about pass/fail gates and don't need to track any quality metrics.
72
+
73
+ ```typescript
74
+ import { runEvals } from '@mastra/core/evals'
75
+ import { checks } from '@mastra/evals/checks'
76
+
77
+ const result = await runEvals({
78
+ data: [{ input: 'What is the weather in Brooklyn?' }],
79
+ target: weatherAgent,
80
+ gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
81
+ })
82
+ ```
83
+
84
+ You must provide at least one scorer or gate — a run with neither throws an error.
85
+
69
86
  ## Thresholds
70
87
 
71
88
  Wrap a scorer in `{ scorer, threshold }` to set pass/fail bounds. The threshold is compared against the scorer's average score across all data items.
package/.docs/docs/getting-started/file-based-agents.md CHANGED
@@ -6,13 +6,15 @@
6
6
 
7
7
  > **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
8
8
 
9
- File-based agents are a new, convention-based way to define Mastra agents and project primitives from a directory structure under `src/mastra/`. You'll like this approach if you want an agent to be self-contained, easy to scan and extend.
9
+ File-based agents are an experimental, convention-based way to define [Mastra agents](https://mastra.ai/docs/agents/overview) and the primitives they use in files under `src/mastra/`, instead of registering them manually on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
10
10
 
11
- Adopting this feature is a fundamental decision about how to structure your project. You'll need to follow the file conventions and be aware of its limitations, namely that you can't use dynamic configuration or runtime wiring.
11
+ This approach reduces glue code and makes the file system itself a direct representation of your [project structure](https://mastra.ai/reference/project-structure), so both you and your coding agent can understand it at a glance.
12
12
 
13
- However, you can use file-based agents, code-defined agents, or both in the same project. All Mastra docs currently use code-first examples. As file-based agents mature, more examples may use this structure where it makes sense.
13
+ You can build your entire project with file-based agents or combine this approach with agents and other primitives defined directly in code, making it easy to adopt incrementally.
14
14
 
15
- Under the hood Mastra is assembling code-defined agents and primitives from the files you create. So explanations and concepts you can find on other docs pages apply to file-based agents as well.
15
+ File-based agents have some limitations while in beta. Not every Mastra feature can be defined in a file yet, and they are not the best fit for dynamic configuration or runtime wiring. When needed, you can define agents and related primitives directly in code.
16
+
17
+ > **Note:** All Mastra documentation currently shows agents and primitives defined directly in code. File-based agents use the same underlying concepts and APIs, so the guidance elsewhere in the docs still applies. As file-based agents mature, more examples may use this structure where appropriate.
16
18
 
17
19
  ## Basic layout
18
20
 
@@ -78,6 +80,7 @@ Map each primitive or feature to its file convention:
78
80
  | [Logger](https://mastra.ai/reference/file-based-agents/logger) | `src/mastra/logger.ts` |
79
81
  | [Server config](https://mastra.ai/reference/file-based-agents/server) | `src/mastra/server.ts` |
80
82
  | [Studio config](https://mastra.ai/reference/file-based-agents/studio) | `src/mastra/studio.ts` |
83
+ | [Schedules](https://mastra.ai/docs/long-running-agents/schedules) | Not yet file-based — create at runtime with `mastra.schedules.create()` |
81
84
 
82
85
  ## Discovery lifecycle
83
86
 
package/.docs/docs/mastra-platform/github.md CHANGED
@@ -9,7 +9,7 @@ The GitHub integration links a Mastra platform project to a GitHub repository. W
9
9
  After a repository is linked, the platform:
10
10
 
11
11
  - Builds and deploys Studio and Server on every push to the configured branches.
12
- - Provisions managed databases and the Mastra gateway API key for projects created from a template.
12
+ - Provisions managed databases and the Gateway API key for projects created from a template.
13
13
  - Surfaces commit, branch, and pull request context on each deploy.
14
14
  - Reports build status back to GitHub as check runs and to the project dashboard with live status badges and inline logs.
15
15
 
@@ -59,7 +59,7 @@ Templates are the fastest way to get started. The platform creates a new reposit
59
59
 
60
60
  3. Configure the template's managed database requirements. Templates can declare required databases (such as Turso or Neon) and you pick the provider and region per requirement.
61
61
 
62
- 4. Add any template-specific environment variables (for example, AI provider API keys). The platform seeds `MASTRA_GATEWAY_API_KEY` and `MASTRA_PLATFORM_ACCESS_TOKEN` automatically so that template code that talks to the Mastra gateway works on the first deploy.
62
+ 4. Add any template-specific environment variables (for example, AI provider API keys). The platform seeds `MASTRA_GATEWAY_API_KEY` and `MASTRA_PLATFORM_ACCESS_TOKEN` automatically so that template code that talks to the Gateway works on the first deploy.
63
63
 
64
64
  5. Select **Create project**. The platform creates the repository, writes a `.mastra-project.json` config file into it, provisions the managed databases, and triggers the initial Studio and Server deploys.
65
65
 
package/.docs/docs/observability/logging.md CHANGED
@@ -6,6 +6,8 @@ Mastra's logging system captures function execution, input data, and output resp
6
6
 
7
7
  When deploying to the Mastra platform, logs are shown in the dashboard. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
8
8
 
9
+ **For AI agents:** Run `npx mastra api log list '{"level":"error","page":0,"perPage":50}'` to inspect recent error logs directly instead of opening Studio or writing a temporary script. The command requires a running Mastra server with observability logging configured; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api log list --schema` before constructing different filters. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
10
+
9
11
  ## Configuring logs with `PinoLogger`
10
12
 
11
13
  When [initializing a new Mastra project](https://mastra.ai/guides/getting-started/quickstart) using the CLI, `PinoLogger` is included by default.
package/.docs/docs/observability/metrics/querying.md CHANGED
@@ -4,6 +4,8 @@
4
4
 
5
5
  Mastra exposes the same five OLAP queries (`getMetricAggregate`, `getMetricBreakdown`, `getMetricTimeSeries`, `getMetricPercentiles`, and discovery helpers) through three surfaces: an in-process store accessor, the runtime HTTP API, and the `mastra api metric` CLI. All three accept the same Zod-validated input shapes, so you can move from a one-off CLI investigation to a programmatic dashboard tool without re-learning the API.
6
6
 
7
+ **For AI agents:** Run `npx mastra api metric aggregate '{"name":"mastra_agent_duration_ms","aggregation":"avg"}'` to query average agent latency directly instead of writing a temporary script. Querying local metrics requires a running Mastra server with an OLAP-capable observability store; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api metric aggregate --schema` before constructing a different query. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
8
+
7
9
  ## When to use this
8
10
 
9
11
  - Build a custom dashboard or KPI tile alongside Studio.
package/.docs/docs/observability/tracing/overview.md CHANGED
@@ -6,6 +6,8 @@ Tracing is the observability signal that records how a request moves through age
6
6
 
7
7
  This page focuses on trace-specific concepts: span hierarchy, sampling, metadata, filtering, trace IDs, and third-party trace context.
8
8
 
9
+ **For AI agents:** Run `npx mastra api trace list '{"page":0,"perPage":20}'` to inspect recent traces directly instead of opening Studio or writing a temporary script. The command requires a running Mastra server with observability configured; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api trace list --schema` before constructing different filters. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
10
+
9
11
  ## When to use tracing
10
12
 
11
13
  - Debug unexpected agent or workflow behavior by inspecting the full execution path.
package/.docs/docs/workflows/overview.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  Workflows let you define complex sequences of tasks using clear, structured steps rather than relying on the reasoning of a single agent. They give you full control over how tasks are broken down, how data moves between them, and what gets executed when. Workflows run using the built-in execution engine by default, or can be deployed to [workflow runners](https://mastra.ai/docs/deployment/workflow-runners) like Inngest for managed infrastructure.
6
6
 
7
- ![Workflows overview](/assets/images/workflows-overview-4509c840549a01ff7386daa5101bda26.jpg)
7
+ **For AI agents:** Run `npx mastra api workflow run start test-workflow '{"inputData":{"message":"Hello, world!"}}'` to start this workflow directly instead of writing a temporary script. The command requires a running Mastra server; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api workflow run start --schema` before constructing different input. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
8
8
 
9
9
  ## When to use workflows
10
10
 
package/.docs/models/environment-variables.md CHANGED
@@ -41,6 +41,7 @@ List of required environment variables for each model provider and gateway suppo
41
41
  | [DeepSeek](https://mastra.ai/models/providers/deepseek) | `deepseek/*` | `DEEPSEEK_API_KEY` |
42
42
  | [DigitalOcean](https://mastra.ai/models/providers/digitalocean) | `digitalocean/*` | `DIGITALOCEAN_ACCESS_TOKEN` |
43
43
  | [DInference](https://mastra.ai/models/providers/dinference) | `dinference/*` | `DINFERENCE_API_KEY` |
44
+ | [EBCloud](https://mastra.ai/models/providers/ebcloud) | `ebcloud/*` | `EBCLOUD_API_KEY` |
44
45
  | [EmpirioLabs AI](https://mastra.ai/models/providers/empiriolabs) | `empiriolabs/*` | `EMPIRIOLABS_API_KEY` |
45
46
  | [evroc](https://mastra.ai/models/providers/evroc) | `evroc/*` | `EVROC_API_KEY` |
46
47
  | [FastRouter](https://mastra.ai/models/providers/fastrouter) | `fastrouter/*` | `FASTROUTER_API_KEY` |
@@ -73,6 +74,7 @@ List of required environment variables for each model provider and gateway suppo
73
74
  | [LMStudio](https://mastra.ai/models/providers/lmstudio) | `lmstudio/*` | `LMSTUDIO_API_KEY` |
74
75
  | [LongCat](https://mastra.ai/models/providers/longcat) | `longcat/*` | `LONGCAT_API_KEY` |
75
76
  | [LucidQuery](https://mastra.ai/models/providers/lucidquery) | `lucidquery/*` | `LUCIDQUERY_API_KEY` |
77
+ | [Lynkr](https://mastra.ai/models/providers/lynkr) | `lynkr/*` | `LYNKR_API_KEY` |
76
78
  | [Meganova](https://mastra.ai/models/providers/meganova) | `meganova/*` | `MEGANOVA_API_KEY` |
77
79
  | [Meta](https://mastra.ai/models/providers/meta) | `meta/*` | `META_MODEL_API_KEY` |
78
80
  | [MiniMax (minimax.io)](https://mastra.ai/models/providers/minimax) | `minimax/*` | `MINIMAX_API_KEY` |
@@ -119,8 +121,10 @@ List of required environment variables for each model provider and gateway suppo
119
121
  | [SiliconFlow (China)](https://mastra.ai/models/providers/siliconflow-cn) | `siliconflow-cn/*` | `SILICONFLOW_CN_API_KEY` |
120
122
  | [Snowflake Cortex](https://mastra.ai/models/providers/snowflake-cortex) | `snowflake-cortex/*` | `SNOWFLAKE_ACCOUNT`, `SNOWFLAKE_CORTEX_PAT` |
121
123
  | [STACKIT](https://mastra.ai/models/providers/stackit) | `stackit/*` | `STACKIT_API_KEY` |
122
- | [StepFun](https://mastra.ai/models/providers/stepfun) | `stepfun/*` | `STEPFUN_API_KEY` |
123
- | [StepFun AI](https://mastra.ai/models/providers/stepfun-ai) | `stepfun-ai/*` | `STEPFUN_API_KEY` |
124
+ | [StepFun (China)](https://mastra.ai/models/providers/stepfun) | `stepfun/*` | `STEPFUN_API_KEY` |
125
+ | [StepFun (Global)](https://mastra.ai/models/providers/stepfun-ai) | `stepfun-ai/*` | `STEPFUN_API_KEY` |
126
+ | [StepFun Step Plan (China)](https://mastra.ai/models/providers/stepfun-step-plan) | `stepfun-step-plan/*` | `STEPFUN_API_KEY` |
127
+ | [StepFun Step Plan (Global)](https://mastra.ai/models/providers/stepfun-ai-step-plan) | `stepfun-ai-step-plan/*` | `STEPFUN_API_KEY` |
124
128
  | [Subconscious](https://mastra.ai/models/providers/subconscious) | `subconscious/*` | `SUBCONSCIOUS_API_KEY` |
125
129
  | [submodel](https://mastra.ai/models/providers/submodel) | `submodel/*` | `SUBMODEL_INSTAGEN_ACCESS_KEY` |
126
130
  | [Synthetic](https://mastra.ai/models/providers/synthetic) | `synthetic/*` | `SYNTHETIC_API_KEY` |
package/.docs/models/gateways/azure-openai.md CHANGED
@@ -57,13 +57,13 @@ import { Mastra } from "@mastra/core";
57
57
  import { AzureOpenAIGateway } from "@mastra/core/llm";
58
58
 
59
59
  export const mastra = new Mastra({
60
- gateways: [
61
- new AzureOpenAIGateway({
60
+ gateways: {
61
+ "azure-openai": new AzureOpenAIGateway({
62
62
  resourceName: "my-openai-resource",
63
63
  apiKey: process.env.AZURE_API_KEY!,
64
64
  deployments: ["gpt-5-4-prod", "gpt-5-4-mini-dev"],
65
65
  }),
66
- ],
66
+ },
67
67
  });
68
68
  ```
69
69
 
@@ -76,8 +76,8 @@ import { Mastra } from "@mastra/core";
76
76
  import { AzureOpenAIGateway } from "@mastra/core/llm";
77
77
 
78
78
  export const mastra = new Mastra({
79
- gateways: [
80
- new AzureOpenAIGateway({
79
+ gateways: {
80
+ "azure-openai": new AzureOpenAIGateway({
81
81
  resourceName: "my-openai-resource",
82
82
  apiKey: process.env.AZURE_API_KEY!,
83
83
  management: {
@@ -88,7 +88,7 @@ export const mastra = new Mastra({
88
88
  resourceGroup: "my-resource-group",
89
89
  },
90
90
  }),
91
- ],
91
+ },
92
92
  });
93
93
  ```
94
94
 
@@ -106,8 +106,8 @@ import { Mastra } from "@mastra/core";
106
106
  import { AzureOpenAIGateway } from "@mastra/core/llm";
107
107
 
108
108
  export const mastra = new Mastra({
109
- gateways: [
110
- new AzureOpenAIGateway({
109
+ gateways: {
110
+ "azure-openai": new AzureOpenAIGateway({
111
111
  resourceName: "my-openai-resource",
112
112
  authentication: {
113
113
  type: "entraId",
@@ -115,7 +115,7 @@ export const mastra = new Mastra({
115
115
  },
116
116
  deployments: ["gpt-5-4-prod", "gpt-5-4-mini-dev"],
117
117
  }),
118
- ],
118
+ },
119
119
  });
120
120
  ```
121
121
 
@@ -138,12 +138,12 @@ import { Mastra } from "@mastra/core";
138
138
  import { AzureOpenAIGateway } from "@mastra/core/llm";
139
139
 
140
140
  export const mastra = new Mastra({
141
- gateways: [
142
- new AzureOpenAIGateway({
141
+ gateways: {
142
+ "azure-openai": new AzureOpenAIGateway({
143
143
  resourceName: "my-openai-resource",
144
144
  apiKey: process.env.AZURE_API_KEY!,
145
145
  }),
146
- ],
146
+ },
147
147
  });
148
148
  ```
149
149
 
@@ -156,14 +156,14 @@ import { Mastra } from "@mastra/core";
156
156
  import { AzureOpenAIGateway } from "@mastra/core/llm";
157
157
 
158
158
  export const mastra = new Mastra({
159
- gateways: [
160
- new AzureOpenAIGateway({
159
+ gateways: {
160
+ "azure-openai": new AzureOpenAIGateway({
161
161
  resourceName: "my-openai-resource",
162
162
  apiKey: process.env.AZURE_API_KEY!,
163
163
  useResponsesAPI: true,
164
164
  deployments: ["my-gpt-5-4-deployment"],
165
165
  }),
166
- ],
166
+ },
167
167
  });
168
168
  ```
169
169
 
package/.docs/models/gateways/mastra.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  # ![Mastra logo](https://mastra.ai/brand/logo.svg)Mastra
4
4
 
5
- The Mastra Memory Gateway is an OpenAI-compatible API proxy with built-in [Observational Memory](https://gateway.mastra.ai/docs/features#observational-memory). Point any HTTP client, SDK, or framework at the gateway and every conversation is automatically remembered without any memory management code.
5
+ The Gateway is an OpenAI-compatible API proxy with built-in [Observational Memory](https://gateway.mastra.ai/docs/features#observational-memory). Point any HTTP client, SDK, or framework at the gateway and every conversation is automatically remembered without any memory management code.
6
6
 
7
- Learn more in the [Memory Gateway documentation](https://gateway.mastra.ai/docs).
7
+ Learn more in the [Gateway documentation](https://gateway.mastra.ai/docs).
8
8
 
9
9
  ## Get an API key
10
10
 
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 4853 models from 151 providers through a single API.
5
+ Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4868 models from 155 providers through a single API.
6
6
 
7
7
  ## Features
8
8
 
package/.docs/models/providers/crossmodel.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # ![CrossModel logo](https://models.dev/logos/crossmodel.svg)CrossModel
4
4
 
5
- Access 37 CrossModel models through Mastra's model router. Authentication is handled automatically using the `CROSSMODEL_API_KEY` environment variable.
5
+ Access 40 CrossModel models through Mastra's model router. Authentication is handled automatically using the `CROSSMODEL_API_KEY` environment variable.
6
6
 
7
7
  Learn more in the [CrossModel documentation](https://www.crossmodel.ai/docs).
8
8
 
@@ -61,6 +61,9 @@ for await (const chunk of stream) {
61
61
  | `crossmodel/openai/gpt-5.4-nano` | 400K | | | | | | $0.20 | $1 |
62
62
  | `crossmodel/openai/gpt-5.5` | 1.1M | | | | | | $5 | $30 |
63
63
  | `crossmodel/openai/gpt-5.5-pro` | 1.1M | | | | | | $30 | $180 |
64
+ | `crossmodel/openai/gpt-5.6-luna` | 1.1M | | | | | | $1 | $6 |
65
+ | `crossmodel/openai/gpt-5.6-sol` | 1.1M | | | | | | $5 | $30 |
66
+ | `crossmodel/openai/gpt-5.6-terra` | 1.1M | | | | | | $3 | $15 |
64
67
  | `crossmodel/qwen/qwen3.6-flash` | 1.0M | | | | | | $0.19 | $1 |
65
68
  | `crossmodel/qwen/qwen3.6-plus` | 1.0M | | | | | | $0.32 | $2 |
66
69
  | `crossmodel/qwen/qwen3.7-max` | 1.0M | | | | | | $2 | $6 |
package/.docs/models/providers/ebcloud.md ADDED
@@ -0,0 +1,76 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # ![EBCloud logo](https://models.dev/logos/ebcloud.svg)EBCloud
4
+
5
+ Access 4 EBCloud models through Mastra's model router. Authentication is handled automatically using the `EBCLOUD_API_KEY` environment variable.
6
+
7
+ Learn more in the [EBCloud documentation](https://docs.ebtech.com/ai/model-api.html).
8
+
9
+ ```bash
10
+ EBCLOUD_API_KEY=your-api-key
11
+ ```
12
+
13
+ ```typescript
14
+ import { Agent } from "@mastra/core/agent";
15
+
16
+ const agent = new Agent({
17
+ id: "my-agent",
18
+ name: "My Agent",
19
+ instructions: "You are a helpful assistant",
20
+ model: "ebcloud/DeepSeek-V4-Flash"
21
+ });
22
+
23
+ // Generate a response
24
+ const response = await agent.generate("Hello!");
25
+
26
+ // Stream a response
27
+ const stream = await agent.stream("Tell me a story");
28
+ for await (const chunk of stream) {
29
+ console.log(chunk);
30
+ }
31
+ ```
32
+
33
+ > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [EBCloud documentation](https://docs.ebtech.com/ai/model-api.html) for details.
34
+
35
+ ## Models
36
+
37
+ | Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
38
+ | --------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
39
+ | `ebcloud/DeepSeek-V4-Flash` | 1.0M | | | | | | $0.14 | $0.29 |
40
+ | `ebcloud/DeepSeek-V4-Pro` | 1.0M | | | | | | $0.43 | $0.86 |
41
+ | `ebcloud/GLM-5.1` | 200K | | | | | | $0.86 | $3 |
42
+ | `ebcloud/Kimi-K2.6` | 262K | | | | | | $0.93 | $4 |
43
+
44
+ ## Advanced configuration
45
+
46
+ ### Custom headers
47
+
48
+ ```typescript
49
+ const agent = new Agent({
50
+ id: "custom-agent",
51
+ name: "custom-agent",
52
+ model: {
53
+ url: "https://maas-api.ebcloud.com/v1",
54
+ id: "ebcloud/DeepSeek-V4-Flash",
55
+ apiKey: process.env.EBCLOUD_API_KEY,
56
+ headers: {
57
+ "X-Custom-Header": "value"
58
+ }
59
+ }
60
+ });
61
+ ```
62
+
63
+ ### Dynamic model selection
64
+
65
+ ```typescript
66
+ const agent = new Agent({
67
+ id: "dynamic-agent",
68
+ name: "Dynamic Agent",
69
+ model: ({ requestContext }) => {
70
+ const useAdvanced = requestContext.task === "complex";
71
+ return useAdvanced
72
+ ? "ebcloud/Kimi-K2.6"
73
+ : "ebcloud/DeepSeek-V4-Flash";
74
+ }
75
+ });
76
+ ```
package/.docs/models/providers/lynkr.md ADDED
@@ -0,0 +1,73 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # ![Lynkr logo](https://models.dev/logos/lynkr.svg)Lynkr
4
+
5
+ Access 1 Lynkr model through Mastra's model router. Authentication is handled automatically using the `LYNKR_API_KEY` environment variable.
6
+
7
+ Learn more in the [Lynkr documentation](https://github.com/Fast-Editor/Lynkr).
8
+
9
+ ```bash
10
+ LYNKR_API_KEY=your-api-key
11
+ ```
12
+
13
+ ```typescript
14
+ import { Agent } from "@mastra/core/agent";
15
+
16
+ const agent = new Agent({
17
+ id: "my-agent",
18
+ name: "My Agent",
19
+ instructions: "You are a helpful assistant",
20
+ model: "lynkr/lynkr-auto"
21
+ });
22
+
23
+ // Generate a response
24
+ const response = await agent.generate("Hello!");
25
+
26
+ // Stream a response
27
+ const stream = await agent.stream("Tell me a story");
28
+ for await (const chunk of stream) {
29
+ console.log(chunk);
30
+ }
31
+ ```
32
+
33
+ > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Lynkr documentation](https://github.com/Fast-Editor/Lynkr) for details.
34
+
35
+ ## Models
36
+
37
+ | Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
38
+ | ------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
39
+ | `lynkr/lynkr-auto` | 128K | | | | | | — | — |
40
+
41
+ ## Advanced configuration
42
+
43
+ ### Custom headers
44
+
45
+ ```typescript
46
+ const agent = new Agent({
47
+ id: "custom-agent",
48
+ name: "custom-agent",
49
+ model: {
50
+ url: "http://127.0.0.1:8081/v1",
51
+ id: "lynkr/lynkr-auto",
52
+ apiKey: process.env.LYNKR_API_KEY,
53
+ headers: {
54
+ "X-Custom-Header": "value"
55
+ }
56
+ }
57
+ });
58
+ ```
59
+
60
+ ### Dynamic model selection
61
+
62
+ ```typescript
63
+ const agent = new Agent({
64
+ id: "dynamic-agent",
65
+ name: "Dynamic Agent",
66
+ model: ({ requestContext }) => {
67
+ const useAdvanced = requestContext.task === "complex";
68
+ return useAdvanced
69
+ ? "lynkr/lynkr-auto"
70
+ : "lynkr/lynkr-auto";
71
+ }
72
+ });
73
+ ```
package/.docs/models/providers/stepfun-ai-step-plan.md ADDED
@@ -0,0 +1,75 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # ![StepFun Step Plan (Global) logo](https://models.dev/logos/stepfun-ai-step-plan.svg)StepFun Step Plan (Global)
4
+
5
+ Access 3 StepFun Step Plan (Global) models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
6
+
7
+ Learn more in the [StepFun Step Plan (Global) documentation](https://platform.stepfun.ai/docs/en/step-plan/integrations/reasoning-api).
8
+
9
+ ```bash
10
+ STEPFUN_API_KEY=your-api-key
11
+ ```
12
+
13
+ ```typescript
14
+ import { Agent } from "@mastra/core/agent";
15
+
16
+ const agent = new Agent({
17
+ id: "my-agent",
18
+ name: "My Agent",
19
+ instructions: "You are a helpful assistant",
20
+ model: "stepfun-ai-step-plan/step-3.5-flash"
21
+ });
22
+
23
+ // Generate a response
24
+ const response = await agent.generate("Hello!");
25
+
26
+ // Stream a response
27
+ const stream = await agent.stream("Tell me a story");
28
+ for await (const chunk of stream) {
29
+ console.log(chunk);
30
+ }
31
+ ```
32
+
33
+ > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [StepFun Step Plan (Global) documentation](https://platform.stepfun.ai/docs/en/step-plan/integrations/reasoning-api) for details.
34
+
35
+ ## Models
36
+
37
+ | Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
38
+ | ------------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
39
+ | `stepfun-ai-step-plan/step-3.5-flash` | 256K | | | | | | — | — |
40
+ | `stepfun-ai-step-plan/step-3.5-flash-2603` | 256K | | | | | | — | — |
41
+ | `stepfun-ai-step-plan/step-3.7-flash` | 256K | | | | | | — | — |
42
+
43
+ ## Advanced configuration
44
+
45
+ ### Custom headers
46
+
47
+ ```typescript
48
+ const agent = new Agent({
49
+ id: "custom-agent",
50
+ name: "custom-agent",
51
+ model: {
52
+ url: "https://api.stepfun.ai/step_plan/v1",
53
+ id: "stepfun-ai-step-plan/step-3.5-flash",
54
+ apiKey: process.env.STEPFUN_API_KEY,
55
+ headers: {
56
+ "X-Custom-Header": "value"
57
+ }
58
+ }
59
+ });
60
+ ```
61
+
62
+ ### Dynamic model selection
63
+
64
+ ```typescript
65
+ const agent = new Agent({
66
+ id: "dynamic-agent",
67
+ name: "Dynamic Agent",
68
+ model: ({ requestContext }) => {
69
+ const useAdvanced = requestContext.task === "complex";
70
+ return useAdvanced
71
+ ? "stepfun-ai-step-plan/step-3.7-flash"
72
+ : "stepfun-ai-step-plan/step-3.5-flash";
73
+ }
74
+ });
75
+ ```
package/.docs/models/providers/stepfun-ai.md CHANGED
@@ -1,10 +1,10 @@
1
1
  > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
2
 
3
- # ![StepFun AI logo](https://models.dev/logos/stepfun-ai.svg)StepFun AI
3
+ # ![StepFun (Global) logo](https://models.dev/logos/stepfun-ai.svg)StepFun (Global)
4
4
 
5
- Access 8 StepFun AI models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
5
+ Access 8 StepFun (Global) models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
6
6
 
7
- Learn more in the [StepFun AI documentation](https://platform.stepfun.ai/docs/en/step-plan/integrations/open-code).
7
+ Learn more in the [StepFun (Global) documentation](https://platform.stepfun.ai/docs/en/overview/concept).
8
8
 
9
9
  ```bash
10
10
  STEPFUN_API_KEY=your-api-key
@@ -30,7 +30,7 @@ for await (const chunk of stream) {
30
30
  }
31
31
  ```
32
32
 
33
- > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [StepFun AI documentation](https://platform.stepfun.ai/docs/en/step-plan/integrations/open-code) for details.
33
+ > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [StepFun (Global) documentation](https://platform.stepfun.ai/docs/en/overview/concept) for details.
34
34
 
35
35
  ## Models
36
36
 
@@ -40,7 +40,7 @@ for await (const chunk of stream) {
40
40
  | `stepfun-ai/step-2-16k` | 16K | | | | | | $5 | $16 |
41
41
  | `stepfun-ai/step-3.5-flash` | 256K | | | | | | $0.10 | $0.30 |
42
42
  | `stepfun-ai/step-3.5-flash-2603` | 256K | | | | | | $0.10 | $0.30 |
43
- | `stepfun-ai/step-3.7-flash` | 256K | | | | | | $0.20 | $1 |
43
+ | `stepfun-ai/step-3.7-flash` | 256K | | | | | | $0.18 | $1 |
44
44
  | `stepfun-ai/step-tts-2` | — | | | | | | — | — |
45
45
  | `stepfun-ai/stepaudio-2.5-asr` | — | | | | | | — | — |
46
46
  | `stepfun-ai/stepaudio-2.5-tts` | — | | | | | | — | — |
@@ -54,7 +54,7 @@ const agent = new Agent({
54
54
  id: "custom-agent",
55
55
  name: "custom-agent",
56
56
  model: {
57
- url: "https://api.stepfun.ai/step_plan/v1",
57
+ url: "https://api.stepfun.ai/v1",
58
58
  id: "stepfun-ai/step-1-32k",
59
59
  apiKey: process.env.STEPFUN_API_KEY,
60
60
  headers: {
package/.docs/models/providers/stepfun-step-plan.md ADDED
@@ -0,0 +1,76 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # ![StepFun Step Plan (China) logo](https://models.dev/logos/stepfun-step-plan.svg)StepFun Step Plan (China)
4
+
5
+ Access 4 StepFun Step Plan (China) models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
6
+
7
+ Learn more in the [StepFun Step Plan (China) documentation](https://platform.stepfun.com/docs/zh/step-plan/integrations/reasoning-api).
8
+
9
+ ```bash
10
+ STEPFUN_API_KEY=your-api-key
11
+ ```
12
+
13
+ ```typescript
14
+ import { Agent } from "@mastra/core/agent";
15
+
16
+ const agent = new Agent({
17
+ id: "my-agent",
18
+ name: "My Agent",
19
+ instructions: "You are a helpful assistant",
20
+ model: "stepfun-step-plan/step-3.5-flash"
21
+ });
22
+
23
+ // Generate a response
24
+ const response = await agent.generate("Hello!");
25
+
26
+ // Stream a response
27
+ const stream = await agent.stream("Tell me a story");
28
+ for await (const chunk of stream) {
29
+ console.log(chunk);
30
+ }
31
+ ```
32
+
33
+ > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [StepFun Step Plan (China) documentation](https://platform.stepfun.com/docs/zh/step-plan/integrations/reasoning-api) for details.
34
+
35
+ ## Models
36
+
37
+ | Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
38
+ | --------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
39
+ | `stepfun-step-plan/step-3.5-flash` | 256K | | | | | | — | — |
40
+ | `stepfun-step-plan/step-3.5-flash-2603` | 256K | | | | | | — | — |
41
+ | `stepfun-step-plan/step-3.7-flash` | 256K | | | | | | — | — |
42
+ | `stepfun-step-plan/step-router-v1` | 256K | | | | | | — | — |
43
+
44
+ ## Advanced configuration
45
+
46
+ ### Custom headers
47
+
48
+ ```typescript
49
+ const agent = new Agent({
50
+ id: "custom-agent",
51
+ name: "custom-agent",
52
+ model: {
53
+ url: "https://api.stepfun.com/step_plan/v1",
54
+ id: "stepfun-step-plan/step-3.5-flash",
55
+ apiKey: process.env.STEPFUN_API_KEY,
56
+ headers: {
57
+ "X-Custom-Header": "value"
58
+ }
59
+ }
60
+ });
61
+ ```
62
+
63
+ ### Dynamic model selection
64
+
65
+ ```typescript
66
+ const agent = new Agent({
67
+ id: "dynamic-agent",
68
+ name: "Dynamic Agent",
69
+ model: ({ requestContext }) => {
70
+ const useAdvanced = requestContext.task === "complex";
71
+ return useAdvanced
72
+ ? "stepfun-step-plan/step-router-v1"
73
+ : "stepfun-step-plan/step-3.5-flash";
74
+ }
75
+ });
76
+ ```
package/.docs/models/providers/stepfun.md CHANGED
@@ -1,10 +1,10 @@
1
1
  > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
2
 
3
- # ![StepFun logo](https://models.dev/logos/stepfun.svg)StepFun
3
+ # ![StepFun (China) logo](https://models.dev/logos/stepfun.svg)StepFun (China)
4
4
 
5
- Access 8 StepFun models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
5
+ Access 8 StepFun (China) models through Mastra's model router. Authentication is handled automatically using the `STEPFUN_API_KEY` environment variable.
6
6
 
7
- Learn more in the [StepFun documentation](https://platform.stepfun.com/docs/zh/overview/concept).
7
+ Learn more in the [StepFun (China) documentation](https://platform.stepfun.com/docs/zh/overview/concept).
8
8
 
9
9
  ```bash
10
10
  STEPFUN_API_KEY=your-api-key
@@ -30,7 +30,7 @@ for await (const chunk of stream) {
30
30
  }
31
31
  ```
32
32
 
33
- > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [StepFun documentation](https://platform.stepfun.com/docs/zh/overview/concept) for details.
33
+ > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [StepFun (China) documentation](https://platform.stepfun.com/docs/zh/overview/concept) for details.
34
34
 
35
35
  ## Models
36
36
 
@@ -40,7 +40,7 @@ for await (const chunk of stream) {
40
40
  | `stepfun/step-2-16k` | 16K | | | | | | $5 | $16 |
41
41
  | `stepfun/step-3.5-flash` | 256K | | | | | | $0.10 | $0.30 |
42
42
  | `stepfun/step-3.5-flash-2603` | 256K | | | | | | $0.10 | $0.30 |
43
- | `stepfun/step-3.7-flash` | 256K | | | | | | $0.20 | $1 |
43
+ | `stepfun/step-3.7-flash` | 256K | | | | | | $0.18 | $1 |
44
44
  | `stepfun/step-tts-2` | — | | | | | | — | — |
45
45
  | `stepfun/stepaudio-2.5-asr` | — | | | | | | — | — |
46
46
  | `stepfun/stepaudio-2.5-tts` | — | | | | | | — | — |
package/.docs/models/providers.md CHANGED
@@ -44,6 +44,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
44
44
  - [Deep Infra](https://mastra.ai/models/providers/deepinfra)
45
45
  - [DigitalOcean](https://mastra.ai/models/providers/digitalocean)
46
46
  - [DInference](https://mastra.ai/models/providers/dinference)
47
+ - [EBCloud](https://mastra.ai/models/providers/ebcloud)
47
48
  - [EmpirioLabs AI](https://mastra.ai/models/providers/empiriolabs)
48
49
  - [evroc](https://mastra.ai/models/providers/evroc)
49
50
  - [FastRouter](https://mastra.ai/models/providers/fastrouter)
@@ -74,6 +75,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
74
75
  - [LMStudio](https://mastra.ai/models/providers/lmstudio)
75
76
  - [LongCat](https://mastra.ai/models/providers/longcat)
76
77
  - [LucidQuery](https://mastra.ai/models/providers/lucidquery)
78
+ - [Lynkr](https://mastra.ai/models/providers/lynkr)
77
79
  - [Meganova](https://mastra.ai/models/providers/meganova)
78
80
  - [Meta](https://mastra.ai/models/providers/meta)
79
81
  - [MiniMax (minimax.io)](https://mastra.ai/models/providers/minimax)
@@ -118,8 +120,10 @@ Direct access to individual AI model providers. Each provider offers unique mode
118
120
  - [SiliconFlow (China)](https://mastra.ai/models/providers/siliconflow-cn)
119
121
  - [Snowflake Cortex](https://mastra.ai/models/providers/snowflake-cortex)
120
122
  - [STACKIT](https://mastra.ai/models/providers/stackit)
121
- - [StepFun](https://mastra.ai/models/providers/stepfun)
122
- - [StepFun AI](https://mastra.ai/models/providers/stepfun-ai)
123
+ - [StepFun (China)](https://mastra.ai/models/providers/stepfun)
124
+ - [StepFun (Global)](https://mastra.ai/models/providers/stepfun-ai)
125
+ - [StepFun Step Plan (China)](https://mastra.ai/models/providers/stepfun-step-plan)
126
+ - [StepFun Step Plan (Global)](https://mastra.ai/models/providers/stepfun-ai-step-plan)
123
127
  - [Subconscious](https://mastra.ai/models/providers/subconscious)
124
128
  - [submodel](https://mastra.ai/models/providers/submodel)
125
129
  - [Synthetic](https://mastra.ai/models/providers/synthetic)
package/.docs/reference/coding-agent/create-coding-agent.md CHANGED
@@ -38,7 +38,7 @@ const agent = createCodingAgent({
38
38
 
39
39
  **signals** (`SignalProvider[]`): Signal providers for the agent. When omitted, defaults to a single TaskSignalProvider.
40
40
 
41
- **errorProcessors** (`Processor[]`): Error processors for the agent. When omitted, defaults to the ECONNRESET/bad-request retry stack plus PrefillErrorHandler and ProviderHistoryCompat.
41
+ **errorProcessors** (`Processor[]`): Error processors for the agent. When omitted, defaults to unknown stream-error retries with specialized ECONNRESET and bad-request policies, plus PrefillErrorHandler and ProviderHistoryCompat.
42
42
 
43
43
  **goal** (`AgentGoalConfig`): Goal configuration. When provided without a prompt, the prompt defaults to DEFAULT\_GOAL\_JUDGE\_PROMPT.
44
44
 
@@ -54,7 +54,7 @@ The factory only fills a default when you don't provide the corresponding field.
54
54
  | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
55
55
  | `workspace` | A [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) backed by `LocalFilesystem` and `LocalSandbox` rooted at the base path. |
56
56
  | `signals` | A single [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider). |
57
- | `errorProcessors` | ECONNRESET and bad-request retry processors plus `PrefillErrorHandler` and `ProviderHistoryCompat`. |
57
+ | `errorProcessors` | Unknown stream-error retries with specialized ECONNRESET and bad-request policies, plus `PrefillErrorHandler` and `ProviderHistoryCompat`. |
58
58
  | `goal.prompt` | `DEFAULT_GOAL_JUDGE_PROMPT` (only when a `goal` is configured). |
59
59
 
60
60
  ### Workspace
@@ -85,12 +85,13 @@ const agent = createCodingAgent({
85
85
 
86
86
  ### Error processors
87
87
 
88
- The default error processors apply a retry policy for transient failures:
88
+ The default [`StreamErrorRetryProcessor`](https://mastra.ai/reference/processors/stream-error-retry-processor) applies these retry policies:
89
89
 
90
+ - Unknown errors left unmatched by provider metadata or a specific matcher retry up to twice with a `3000ms` delay. Known authorization failures surface immediately.
90
91
  - Network resets (`ECONNRESET` / `socket hang up`) retry up to twice with exponential backoff (`1000ms * 2^retryCount`, capped at `30000ms`).
91
92
  - Bad-request errors retry once after `2000ms`.
92
93
 
93
- `PrefillErrorHandler` and `ProviderHistoryCompat` are also included for provider compatibility.
94
+ Specific network-reset and bad-request policies take precedence over the unknown-error policy. Passing `errorProcessors` replaces the default processor stack. `PrefillErrorHandler` and `ProviderHistoryCompat` are also included for provider compatibility.
94
95
 
95
96
  ## Related
96
97
 
package/.docs/reference/evals/run-evals.md CHANGED
@@ -56,9 +56,9 @@ result.thresholdResults // [{ id, passed, averageScore, threshold }]
56
56
 
57
57
  **data** (`RunEvalsDataItem[]`): Array of test cases with input data and optional ground truth.
58
58
 
59
- **scorers** (`ScorerEntry[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to use. Each entry is either a bare MastraScorer or { scorer, threshold } for threshold tracking. An AgentScorerConfig object separates agent-level and trajectory scorers. A WorkflowScorerConfig object specifies scorers for the workflow, individual steps, and trajectory.
59
+ **scorers** (`ScorerEntry[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to use. Each entry is either a bare MastraScorer or { scorer, threshold } for threshold tracking. An AgentScorerConfig object separates agent-level and trajectory scorers. A WorkflowScorerConfig object specifies scorers for the workflow, individual steps, and trajectory. Optional when at least one gate is provided (gate-only runs).
60
60
 
61
- **gates** (`MastraScorer[]`): Scorers that must score 1.0 for the run to pass. If any gate averages below 1.0 across data items, the verdict is failed. Gates run before regular scorers on each data item.
61
+ **gates** (`MastraScorer[]`): Scorers that must score 1.0 for the run to pass. If any gate averages below 1.0 across data items, the verdict is failed. Gates run before regular scorers on each data item. When provided, scorers may be omitted.
62
62
 
63
63
  **targetOptions** (`AgentExecutionOptions | WorkflowRunOptions`): Options forwarded to the target during execution. For agents: options passed to agent.generate() (e.g. maxSteps, modelSettings, instructions). For workflows: options passed to run.start() (e.g. perStep, outputOptions, initialState).
64
64
 
package/.docs/reference/mastra-platform/api.md CHANGED
@@ -107,4 +107,4 @@ The root URL for the endpoints below is: `/v1/gateway`
107
107
 
108
108
  ## Gateway proxy endpoints
109
109
 
110
- Visit the [Memory Gateway documentation](https://gateway.mastra.ai/docs) for more details.
110
+ Visit the [Gateway documentation](https://gateway.mastra.ai/docs) for more details.
package/.docs/reference/observability/metrics/automatic-metrics.md CHANGED
@@ -23,13 +23,13 @@ If metrics aren't available, see [troubleshooting](#troubleshooting).
23
23
 
24
24
  Duration metrics record execution time in milliseconds, calculated from the span's start and end timestamps. Each duration metric includes a `status` label set to `ok` or `error`, derived from the span's status.
25
25
 
26
- | Metric name | Span type | Description |
27
- | ------------------------------ | ---------------------------- | ------------------------------------------------------- |
28
- | `mastra_agent_duration_ms` | `AGENT_RUN` | Execution time of an agent run |
29
- | `mastra_tool_duration_ms` | `TOOL_CALL`, `MCP_TOOL_CALL` | Execution time of a tool call, including MCP tool calls |
30
- | `mastra_workflow_duration_ms` | `WORKFLOW_RUN` | Execution time of a workflow run |
31
- | `mastra_model_duration_ms` | `MODEL_GENERATION` | Execution time of a model generation |
32
- | `mastra_processor_duration_ms` | `PROCESSOR_RUN` | Execution time of a processor run |
26
+ | Metric name | Span type | Description |
27
+ | ------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------- |
28
+ | `mastra_agent_duration_ms` | `AGENT_RUN` | Execution time of an agent run |
29
+ | `mastra_tool_duration_ms` | `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL` | Execution time of a tool call, including MCP and provider-executed tool calls |
30
+ | `mastra_workflow_duration_ms` | `WORKFLOW_RUN` | Execution time of a workflow run |
31
+ | `mastra_model_duration_ms` | `MODEL_GENERATION` | Execution time of a model generation |
32
+ | `mastra_processor_duration_ms` | `PROCESSOR_RUN` | Execution time of a processor run |
33
33
 
34
34
  ## Token usage metrics
35
35
 
@@ -124,7 +124,7 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
124
124
  ### Duration metrics are missing
125
125
 
126
126
  - **Span has timestamps**: Duration is calculated from `startTime` and `endTime`. If either is missing, the metric is skipped.
127
- - **Span type maps to a metric**: Only `AGENT_RUN`, `TOOL_CALL`, `MCP_TOOL_CALL`, `WORKFLOW_RUN`, `MODEL_GENERATION`, and `PROCESSOR_RUN` spans produce duration metrics.
127
+ - **Span type maps to a metric**: Only `AGENT_RUN`, `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL`, `WORKFLOW_RUN`, `MODEL_GENERATION`, and `PROCESSOR_RUN` spans produce duration metrics.
128
128
 
129
129
  ### Token metrics are missing
130
130
 
package/.docs/reference/observability/tracing/exporters/braintrust.md CHANGED
@@ -92,6 +92,7 @@ const exporter = new BraintrustExporter({
92
92
  | `MODEL_CHUNK` | `llm` |
93
93
  | `TOOL_CALL` | `tool` |
94
94
  | `MCP_TOOL_CALL` | `tool` |
95
+ | `PROVIDER_TOOL_CALL` | `tool` |
95
96
  | `WORKFLOW_CONDITIONAL_EVAL` | `function` |
96
97
  | `WORKFLOW_WAIT_EVENT` | `function` |
97
98
  | All others | `task` |
package/.docs/reference/observability/tracing/exporters/datadog.md CHANGED
@@ -95,15 +95,16 @@ const exporter = new DatadogExporter({
95
95
 
96
96
  Mastra span types are mapped to Datadog LLM Observability span kinds:
97
97
 
98
- | Mastra SpanType | Datadog Kind |
99
- | ------------------ | ------------ |
100
- | `AGENT_RUN` | `agent` |
101
- | `MODEL_GENERATION` | `workflow` |
102
- | `MODEL_STEP` | `llm` |
103
- | `TOOL_CALL` | `tool` |
104
- | `MCP_TOOL_CALL` | `tool` |
105
- | `WORKFLOW_RUN` | `workflow` |
106
- | All other types | `task` |
98
+ | Mastra SpanType | Datadog Kind |
99
+ | -------------------- | ------------ |
100
+ | `AGENT_RUN` | `agent` |
101
+ | `MODEL_GENERATION` | `workflow` |
102
+ | `MODEL_STEP` | `llm` |
103
+ | `TOOL_CALL` | `tool` |
104
+ | `MCP_TOOL_CALL` | `tool` |
105
+ | `PROVIDER_TOOL_CALL` | `tool` |
106
+ | `WORKFLOW_RUN` | `workflow` |
107
+ | All other types | `task` |
107
108
 
108
109
  All unmapped span types (including `MODEL_CHUNK`, `WORKFLOW_STEP`, `GENERIC`, and future span types) automatically default to `task`.
109
110
 
package/.docs/reference/observability/tracing/exporters/langsmith.md CHANGED
@@ -73,13 +73,14 @@ const exporter = new LangSmithExporter({
73
73
 
74
74
  ## Span type mapping
75
75
 
76
- | Span Type | LangSmith Type |
77
- | ------------------ | -------------- |
78
- | `MODEL_GENERATION` | `llm` |
79
- | `MODEL_CHUNK` | `llm` |
80
- | `TOOL_CALL` | `tool` |
81
- | `MCP_TOOL_CALL` | `tool` |
82
- | All others | `chain` |
76
+ | Span Type | LangSmith Type |
77
+ | -------------------- | -------------- |
78
+ | `MODEL_GENERATION` | `llm` |
79
+ | `MODEL_CHUNK` | `llm` |
80
+ | `TOOL_CALL` | `tool` |
81
+ | `MCP_TOOL_CALL` | `tool` |
82
+ | `PROVIDER_TOOL_CALL` | `tool` |
83
+ | All others | `chain` |
83
84
 
84
85
  ## `withLangsmithMetadata`
85
86
 
package/.docs/reference/observability/tracing/exporters/posthog.md CHANGED
@@ -80,15 +80,16 @@ const exporter = new PosthogExporter({
80
80
 
81
81
  ## Span type mapping
82
82
 
83
- | Mastra Span Type | PostHog Event Type |
84
- | ------------------- | ------------------ |
85
- | `MODEL_GENERATION` | `$ai_generation` |
86
- | `MODEL_STEP` | `$ai_generation` |
87
- | `MODEL_CHUNK` | `$ai_span` |
88
- | `TOOL_CALL` | `$ai_span` |
89
- | `MCP_TOOL_CALL` | `$ai_span` |
90
- | `PROCESSOR_RUN` | `$ai_span` |
91
- | `AGENT_RUN` | `$ai_span` |
92
- | `WORKFLOW_RUN` | `$ai_span` |
93
- | All other workflows | `$ai_span` |
94
- | `GENERIC` | `$ai_span` |
83
+ | Mastra Span Type | PostHog Event Type |
84
+ | -------------------- | ------------------ |
85
+ | `MODEL_GENERATION` | `$ai_generation` |
86
+ | `MODEL_STEP` | `$ai_generation` |
87
+ | `MODEL_CHUNK` | `$ai_span` |
88
+ | `TOOL_CALL` | `$ai_span` |
89
+ | `MCP_TOOL_CALL` | `$ai_span` |
90
+ | `PROVIDER_TOOL_CALL` | `$ai_span` |
91
+ | `PROCESSOR_RUN` | `$ai_span` |
92
+ | `AGENT_RUN` | `$ai_span` |
93
+ | `WORKFLOW_RUN` | `$ai_span` |
94
+ | All other workflows | `$ai_span` |
95
+ | `GENERIC` | `$ai_span` |
package/.docs/reference/observability/tracing/exporters/sentry.md CHANGED
@@ -117,6 +117,7 @@ Mastra span types are mapped to Sentry operations:
117
117
  | `MODEL_CHUNK` | _(skipped)_ |
118
118
  | `TOOL_CALL` | `gen_ai.execute_tool` |
119
119
  | `MCP_TOOL_CALL` | `gen_ai.execute_tool` |
120
+ | `PROVIDER_TOOL_CALL` | `gen_ai.execute_tool` |
120
121
  | `WORKFLOW_RUN` | `workflow.run` |
121
122
  | `WORKFLOW_STEP` | `workflow.step` |
122
123
  | `WORKFLOW_CONDITIONAL` | `workflow.conditional` |
package/.docs/reference/observability/tracing/interfaces.md CHANGED
@@ -46,6 +46,7 @@ interface SpanTypeMap {
46
46
  MODEL_CHUNK: ModelChunkAttributes
47
47
  TOOL_CALL: ToolCallAttributes
48
48
  CLIENT_TOOL_CALL: ClientToolCallAttributes
49
+ PROVIDER_TOOL_CALL: ProviderToolCallAttributes
49
50
  MCP_TOOL_CALL: MCPToolCallAttributes
50
51
  PROCESSOR_RUN: ProcessorRunAttributes
51
52
  WORKFLOW_STEP: WorkflowStepAttributes
@@ -314,6 +315,14 @@ enum SpanType {
314
315
  */
315
316
  CLIENT_TOOL_CALL = 'client_tool_call',
316
317
 
318
+ /**
319
+ * Provider-executed (server-side) tool span. Reconstructed from
320
+ * tool-call and tool-result stream chunks for tools the model
321
+ * provider executes (e.g. Anthropic code execution, server-side
322
+ * web search). Opened on tool-call chunk, closed on tool-result.
323
+ */
324
+ PROVIDER_TOOL_CALL = 'provider_tool_call',
325
+
317
326
  /** Workflow run - root span for workflow processes */
318
327
  WORKFLOW_RUN = 'workflow_run',
319
328
 
package/.docs/reference/processors/stream-error-retry-processor.md CHANGED
@@ -35,6 +35,31 @@ When the error is retryable, the processor returns `{ retry: true }`. It doesn't
35
35
 
36
36
  When `delayMs` is set, the processor waits before signaling a retry. This is useful for transient network errors like `ECONNRESET` where immediately retrying is likely to fail again. The delay can be a fixed number of milliseconds or a function evaluated with the error args (for example, to implement exponential backoff).
37
37
 
38
+ ## Retry unknown errors
39
+
40
+ Set `retryUnknownErrors` to retry errors that don't match provider metadata, the built-in OpenAI matcher, or a custom matcher. Unknown-error retries use the processor-level `maxRetries` and `delayMs` values. Known authorization failures, including HTTP `401` and `403` responses, aren't retried:
41
+
42
+ ```typescript
43
+ import { Agent } from '@mastra/core/agent'
44
+ import { StreamErrorRetryProcessor } from '@mastra/core/processors'
45
+
46
+ export const agent = new Agent({
47
+ id: 'resilient-agent',
48
+ name: 'Resilient agent',
49
+ instructions: 'You are a helpful assistant.',
50
+ model: 'openai/gpt-5',
51
+ errorProcessors: [
52
+ new StreamErrorRetryProcessor({
53
+ retryUnknownErrors: true,
54
+ maxRetries: 2,
55
+ delayMs: 3000,
56
+ }),
57
+ ],
58
+ })
59
+ ```
60
+
61
+ Specific matcher policies still take precedence over the unknown-error values. The option defaults to `false`, so unknown errors aren't retried unless you enable it.
62
+
38
63
  ## Delaying retries
39
64
 
40
65
  Use `delayMs` with a custom matcher to retry transient network resets with a wait:
package/.docs/reference/server/register-api-route.md CHANGED
@@ -28,7 +28,7 @@ registerApiRoute("/items/:itemId", { ... })
28
28
 
29
29
  **handler** (`Handler`): Route handler function receiving Hono Context. Use either handler or createHandler, not both.
30
30
 
31
- **createHandler** (`(c: Context) => Promise<Handler>`): Async factory function to create the handler. Use either handler or createHandler, not both.
31
+ **createHandler** (`({ mastra }: { mastra: Mastra }) => Promise<ApiRouteHandler>`): Async factory that receives the Mastra instance and returns the route handler. Runs once at server startup, so it can perform one-time setup. Use either handler or createHandler, not both.
32
32
 
33
33
  **middleware** (`MiddlewareHandler | MiddlewareHandler[]`): Route-specific middleware functions
34
34
 
@@ -229,12 +229,13 @@ For routes that need async initialization:
229
229
  ```typescript
230
230
  registerApiRoute('/dynamic', {
231
231
  method: 'GET',
232
- createHandler: async c => {
233
- // Perform async setup
232
+ createHandler: async ({ mastra }) => {
233
+ // Perform one-time async setup
234
234
  const config = await loadConfig()
235
+ const agent = mastra.getAgent('weatherAgent')
235
236
 
236
237
  return async c => {
237
- return c.json({ config })
238
+ return c.json({ config, agent: agent.name })
238
239
  }
239
240
  },
240
241
  })
package/.docs/reference/templates/overview.md CHANGED
@@ -15,7 +15,7 @@ Mastra templates are pre-built project structures that demonstrate specific use
15
15
 
16
16
  The following templates demonstrate Gateway-first Mastra applications:
17
17
 
18
- - `template-docs-expert`: Answers documentation questions with Mastra Gateway web search, citations, memory, and structured responses.
18
+ - `template-docs-expert`: Answers documentation questions with Gateway web search, citations, memory, and structured responses.
19
19
  - `template-browser-agent`: Uses AgentBrowser to browse, inspect, and interact with web pages.
20
20
  - `template-meeting-notes`: Turns Zoom transcripts or uploaded transcripts into structured notes with decisions and action items.
21
21
  - `template-company-knowledge`: Indexes Linear and Notion content into pgvector and answers internal knowledge questions.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # @mastra/mcp-docs-server
2
2
 
3
+ ## 1.2.7-alpha.15
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`25e7c12`](https://github.com/mastra-ai/mastra/commit/25e7c126a770069ae7fb7ecf1d2adb40e017b009), [`1ce5121`](https://github.com/mastra-ai/mastra/commit/1ce512155d122bb21f47d98383e82ffbf84b39e8), [`3cfc47a`](https://github.com/mastra-ai/mastra/commit/3cfc47a6b89940aadd0f46fb01ae9624a73a865d), [`2bb7817`](https://github.com/mastra-ai/mastra/commit/2bb78176112fde628483de2830528f7eee911e56), [`51d9870`](https://github.com/mastra-ai/mastra/commit/51d987032c689c2855374d0f244f5d654da809d1), [`5cab274`](https://github.com/mastra-ai/mastra/commit/5cab2744250e22d12fefa7b32637dce224233cee), [`7fa27d3`](https://github.com/mastra-ai/mastra/commit/7fa27d3b6f5ed68cd34e454a4d3ad9c482a0cfbc), [`a58dcbb`](https://github.com/mastra-ai/mastra/commit/a58dcbb546d7e1d65ebdc1f39e55f0908fcd9391), [`153bd3b`](https://github.com/mastra-ai/mastra/commit/153bd3b396bdfed6b74cf43de12db8fd2d83c04a), [`07bb863`](https://github.com/mastra-ai/mastra/commit/07bb8631919c6f7cf377dccd45b096e0f17fbed0), [`8a586ec`](https://github.com/mastra-ai/mastra/commit/8a586eca9a4914f31dff6140d0d45ac375b00669), [`3927473`](https://github.com/mastra-ai/mastra/commit/392747323ddb10c643d12be7b9ae913159dfaeed), [`dce50dc`](https://github.com/mastra-ai/mastra/commit/dce50dc9a1c1fcd0f427bb5f6250ec74910cb04b), [`634caff`](https://github.com/mastra-ai/mastra/commit/634caff29a9200ad058b67d53f96d9e5832fb8a2)]:
8
+ - @mastra/core@1.51.0-alpha.7
9
+
3
10
  ## 1.2.7-alpha.13
4
11
 
5
12
  ### Patch Changes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mastra/mcp-docs-server",
3
- "version": "1.2.7-alpha.14",
3
+ "version": "1.2.7-alpha.16",
4
4
  "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -28,7 +28,7 @@
28
28
  "jsdom": "^26.1.0",
29
29
  "local-pkg": "^1.1.2",
30
30
  "zod": "^4.4.3",
31
- "@mastra/core": "1.51.0-alpha.6",
31
+ "@mastra/core": "1.51.0-alpha.7",
32
32
  "@mastra/mcp": "^1.14.0-alpha.0"
33
33
  },
34
34
  "devDependencies": {
@@ -45,9 +45,9 @@
45
45
  "tsx": "^4.22.4",
46
46
  "typescript": "^6.0.3",
47
47
  "vitest": "4.1.9",
48
- "@internal/lint": "0.0.113",
49
- "@mastra/core": "1.51.0-alpha.6",
50
- "@internal/types-builder": "0.0.88"
48
+ "@internal/types-builder": "0.0.88",
49
+ "@mastra/core": "1.51.0-alpha.7",
50
+ "@internal/lint": "0.0.113"
51
51
  },
52
52
  "homepage": "https://mastra.ai",
53
53
  "repository": {