Unclaimed project
Are you a maintainer of mastra? Claim this project to take control of your public changelog and roadmap.
Changelog
From the team behind Gatsby, Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
Last updated about 21 hours ago
Add structured output support to agent.network() method. Users can now pass a structuredOutput option with a Zod schema to get typed results from network execution. (#11701)
The stream exposes .object (Promise) and .objectStream (ReadableStream) getters, and emits network-object and network-object-result chunk types. The structured output is generated after task completion using the provided schema.
Interactive roadmaps, guides and other educational content to help developers grow in their careers.
Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞
This is the repo for Vue 2. For Vue 3, go to https://github.com/vuejs/core
const stream = await agent.network('Research AI trends', {
structuredOutput: {
schema: z.object({
summary: z.string(),
recommendations: z.array(z.string()),
}),
},
});
const result = await stream.object;
// result is typed: { summary: string; recommendations: string[] }
feat(observability): add zero-config environment variable support for all exporters (#11686)
All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URLBRAINTRUST_API_KEY, BRAINTRUST_ENDPOINTPOSTHOG_API_KEY, POSTHOG_HOSTARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAMEDASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASETSIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINTNEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINTTRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINTLMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_IDExample usage:
// Zero-config - reads from environment variables
new LangfuseExporter();
new BraintrustExporter();
new PosthogExporter();
new ArizeExporter();
new OtelExporter({ provider: { signoz: {} } });
Explicit configuration still works and takes precedence over environment variables.
feat(observability): add zero-config environment variable support for all exporters (#11686)
All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URLBRAINTRUST_API_KEY, BRAINTRUST_ENDPOINTPOSTHOG_API_KEY, POSTHOG_HOSTARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAMEDASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASETSIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINTNEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINTTRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINTLMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_IDExample usage:
// Zero-config - reads from environment variables
new LangfuseExporter();
new BraintrustExporter();
new PosthogExporter();
new ArizeExporter();
new OtelExporter({ provider: { signoz: {} } });
Explicit configuration still works and takes precedence over environment variables.
Add structured output support to agent.network() method. Users can now pass a structuredOutput option with a Zod schema to get typed results from network execution. (#11701)
The stream exposes .object (Promise) and .objectStream (ReadableStream) getters, and emits network-object and network-object-result chunk types. The structured output is generated after task completion using the provided schema.
const stream = await agent.network('Research AI trends', {
structuredOutput: {
schema: z.object({
summary: z.string(),
recommendations: z.array(z.string()),
}),
},
});
const result = await stream.object;
// result is typed: { summary: string; recommendations: string[] }
Add additional context to workflow onFinish and onError callbacks (#11705)
The onFinish and onError lifecycle callbacks now receive additional properties:
runId - The unique identifier for the workflow runworkflowId - The workflow's identifierresourceId - Optional resource identifier (if provided when creating the run)getInitData() - Function that returns the initial input data passed to the workflowmastra - The Mastra instance (if workflow is registered with Mastra)requestContext - Request-scoped context datalogger - The workflow's logger instancestate - The workflow's current state objectconst workflow = createWorkflow({
id: 'order-processing',
inputSchema: z.object({ orderId: z.string() }),
outputSchema: z.object({ status: z.string() }),
options: {
onFinish: async ({ runId, workflowId, getInitData, logger, state, mastra }) => {
const inputData = getInitData();
logger.info(`Workflow ${workflowId} run ${runId} completed`, {
orderId: inputData.orderId,
finalState: state,
});
// Access other Mastra components if needed
const agent = mastra?.getAgent('notification-agent');
},
onError: async ({ runId, workflowId, error, logger, requestContext }) => {
logger.error(`Workflow ${workflowId} run ${runId} failed: ${error?.message}`);
// Access request context for additional debugging
const userId = requestContext.get('userId');
},
},
});
Make initialState optional in studio (#11744)
Refactor: consolidate duplicate applyMessages helpers in workflow.ts (#11688)
defaultSource parameter to ProcessorRunner.applyMessagesToMessageList to support both 'input' and 'response' default sourcesapplyMessages helper functions from workflow.ts (in input, outputResult, and outputStep phases)ProcessorRunner.applyMessagesToMessageList static methodThis is an internal refactoring with no changes to external behavior.
Cache processor instances in MastraMemory to preserve embedding cache across calls (#11720) Fixed issue where getInputProcessors() and getOutputProcessors() created new processor instances on each call, causing the SemanticRecall embedding cache to be discarded. Processor instances (SemanticRecall, WorkingMemory, MessageHistory) are now cached and reused, reducing unnecessary embedding API calls and improving latency. Also added cache invalidation when setStorage(), setVector(), or setEmbedder() are called to ensure processors use updated dependencies. Fixes #11455
Added a Datadog LLM Observability exporter for Mastra applications. (#11305)
This exporter integrates with Datadog's LLM Observability product to provide comprehensive tracing and monitoring for AI/LLM applications built with Mastra.
Required settings:
mlApp: Groups traces under an ML application name (required)apiKey: Datadog API key (required for agentless mode)Optional settings:
site: Datadog site (datadoghq.com, datadoghq.eu, us3.datadoghq.com)agentless: true for direct HTTPS (default), false for local agentservice, env: APM taggingintegrationsEnabled: Enable dd-trace auto-instrumentation (default: false)import { Mastra } from '@mastra/core';
import { Observability } from '@mastra/observability';
import { DatadogExporter } from '@mastra/datadog';
const mastra = new Mastra({
observability: new Observability({
configs: {
datadog: {
serviceName: 'my-service',
exporters: [
new DatadogExporter({
mlApp: 'my-llm-app',
apiKey: process.env.DD_API_KEY,
}),
],
},
},
}),
});
This is an initial experimental beta release. Breaking changes may occur in future versions as the API evolves.
Added createServe factory function to support multiple web framework adapters for Inngest workflows. (#11667)
Previously, the serve function only supported Hono. Now you can use any framework adapter provided by the Inngest package (Express, Fastify, Koa, Next.js, and more).
Before (Hono only)
import { serve } from '@mastra/inngest';
// Only worked with Hono
app.all('/api/inngest', c => serve({ mastra, inngest })(c));
After (any framework)
import { createServe } from '@mastra/inngest';
import { serve as expressAdapter } from 'inngest/express';
import { serve as fastifyAdapter } from 'inngest/fastify';
// Express
app.use('/api/inngest', createServe(expressAdapter)({ mastra, inngest }));
// Fastify
fastify.route({
method: ['GET', 'POST', 'PUT'],
url: '/api/inngest',
handler: createServe(fastifyAdapter)({ mastra, inngest }),
});
The existing serve export remains available for backward compatibility with Hono.
Fixes #10053
Add additional context to workflow onFinish and onError callbacks (#11705)
The onFinish and onError lifecycle callbacks now receive additional properties:
runId - The unique identifier for the workflow runworkflowId - The workflow's identifierresourceId - Optional resource identifier (if provided when creating the run)getInitData() - Function that returns the initial input data passed to the workflowmastra - The Mastra instance (if workflow is registered with Mastra)requestContext - Request-scoped context datalogger - The workflow's logger instancestate - The workflow's current state objectconst workflow = createWorkflow({
id: 'order-processing',
inputSchema: z.object({ orderId: z.string() }),
outputSchema: z.object({ status: z.string() }),
options: {
onFinish: async ({ runId, workflowId, getInitData, logger, state, mastra }) => {
const inputData = getInitData();
logger.info(`Workflow ${workflowId} run ${runId} completed`, {
orderId: inputData.orderId,
finalState: state,
});
// Access other Mastra components if needed
const agent = mastra?.getAgent('notification-agent');
},
onError: async ({ runId, workflowId, error, logger, requestContext }) => {
logger.error(`Workflow ${workflowId} run ${runId} failed: ${error?.message}`);
// Access request context for additional debugging
const userId = requestContext.get('userId');
},
},
});
feat(observability): add zero-config environment variable support for all exporters (#11686)
All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URLBRAINTRUST_API_KEY, BRAINTRUST_ENDPOINTPOSTHOG_API_KEY, POSTHOG_HOSTARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAMEDASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASETSIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINTNEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINTTRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINTLMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_IDExample usage:
// Zero-config - reads from environment variables
new LangfuseExporter();
new BraintrustExporter();
new PosthogExporter();
new ArizeExporter();
new OtelExporter({ provider: { signoz: {} } });
Explicit configuration still works and takes precedence over environment variables.
feat(mcp-docs-server): add embedded docs MCP tools (#11532)
Adds 5 new MCP tools to read embedded documentation from installed @mastra/* packages:
These tools enable AI coding agents to understand Mastra packages by reading documentation directly from node_modules.
feat(observability): add zero-config environment variable support for all exporters (#11686)
All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URLBRAINTRUST_API_KEY, BRAINTRUST_ENDPOINTPOSTHOG_API_KEY, POSTHOG_HOSTARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAMEDASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASETSIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINTNEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINTTRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINTLMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_IDExample usage:
// Zero-config - reads from environment variables
new LangfuseExporter();
new BraintrustExporter();
new PosthogExporter();
new ArizeExporter();
new OtelExporter({ provider: { signoz: {} } });
Explicit configuration still works and takes precedence over environment variables.
feat(observability): add zero-config environment variable support for all exporters (#11686)
All observability exporters now support zero-config setup via environment variables. Set the appropriate environment variables and instantiate exporters with no configuration:
LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URLBRAINTRUST_API_KEY, BRAINTRUST_ENDPOINTPOSTHOG_API_KEY, POSTHOG_HOSTARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAMEDASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASETSIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINTNEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINTTRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINTLMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_IDExample usage:
// Zero-config - reads from environment variables
new LangfuseExporter();
new BraintrustExporter();
new PosthogExporter();
new ArizeExporter();
new OtelExporter({ provider: { signoz: {} } });
Explicit configuration still works and takes precedence over environment variables.
ai package peer dependency to enable compatibility with AI SDK v6. The rag package doesn't directly use the ai package, so this peer dependency was unnecessarily constraining version compatibility. (#11724)Fix oneOf schema conversion generating invalid JavaScript (#11626)
The upstream json-schema-to-zod library generates TypeScript syntax (reduce<z.ZodError[]>) when converting oneOf schemas. This TypeScript generic annotation fails when evaluated at runtime with Function(), causing schema resolution to fail.
The fix removes TypeScript generic syntax from the generated output, producing valid JavaScript that can be evaluated at runtime. This resolves issues where MCP tools with oneOf in their output schemas would fail validation.
Replace deprecated client.getTraces with a client.listTraces (#11711)
Fix query parameter parsing for complex nested optional types (#11711)
Fixes an issue where complex query parameters (like startedAt and endedAt date range filters) would fail with "Expected object, received string" errors when using the listTraces API.
The fix addresses two issues:
.partial() on already-optional fields)Full Changelog: 8edb597