github mastra-ai/mastra @mastra/core@1.0.0-beta.21
January 9, 2026
on GitHub

one day ago

Changelog

@mastra/ai-sdk@1.0.0-beta.14

Patch Changes

  • 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[] }

@mastra/arize@1.0.0-beta.12

Minor Changes

  • 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: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
    • Braintrust: BRAINTRUST_API_KEY, BRAINTRUST_ENDPOINT
    • PostHog: POSTHOG_API_KEY, POSTHOG_HOST
    • Arize/Phoenix: ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
    • OTEL Providers:
      • Dash0: DASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASET
      • SigNoz: SIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINT
      • New Relic: NEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINT
      • Traceloop: TRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINT
      • Laminar: LMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_ID

    Example 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.

@mastra/braintrust@1.0.0-beta.12

Minor Changes

  • 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: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
    • Braintrust: BRAINTRUST_API_KEY, BRAINTRUST_ENDPOINT
    • PostHog: POSTHOG_API_KEY, POSTHOG_HOST
    • Arize/Phoenix: ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
    • OTEL Providers:
      • Dash0: DASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASET
      • SigNoz: SIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINT
      • New Relic: NEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINT
      • Traceloop: TRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINT
      • Laminar: LMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_ID

    Example 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.

@mastra/core@1.0.0-beta.21

Minor Changes

  • 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[] }

Patch Changes

  • 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 run
    • workflowId - The workflow's identifier
    • resourceId - Optional resource identifier (if provided when creating the run)
    • getInitData() - Function that returns the initial input data passed to the workflow
    • mastra - The Mastra instance (if workflow is registered with Mastra)
    • requestContext - Request-scoped context data
    • logger - The workflow's logger instance
    • state - The workflow's current state object 
    const 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)

    • Added optional defaultSource parameter to ProcessorRunner.applyMessagesToMessageList to support both 'input' and 'response' default sources
    • Removed 3 duplicate inline applyMessages helper functions from workflow.ts (in input, outputResult, and outputStep phases)
    • All phases now use the shared ProcessorRunner.applyMessagesToMessageList static method

    This 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

@mastra/datadog@1.0.0-beta.2

Minor Changes

  • 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.

    • LLM Observability Integration: Exports traces to Datadog's dedicated LLM Observability product
    • Dual Mode Support: Works with direct HTTPS (agentless) or through a local Datadog Agent
    • Span Type Mapping: Automatically maps Mastra span types to Datadog LLMObs kinds (llm, agent, tool, workflow, task)
    • Message Formatting: LLM inputs/outputs are formatted as message arrays for proper visualization in Datadog
    • Token Metrics: Captures inputTokens, outputTokens, totalTokens, reasoningTokens, and cached tokens
    • Error Tracking: Error spans include detailed error info (message, ID, domain, category)
    • Hierarchical Traces: Tree-based span emission preserves parent-child relationships

    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 agent
    • service, env: APM tagging
    • integrationsEnabled: 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.

@mastra/inngest@1.0.0-beta.12

Minor Changes

  • 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

Patch Changes

  • 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 run
    • workflowId - The workflow's identifier
    • resourceId - Optional resource identifier (if provided when creating the run)
    • getInitData() - Function that returns the initial input data passed to the workflow
    • mastra - The Mastra instance (if workflow is registered with Mastra)
    • requestContext - Request-scoped context data
    • logger - The workflow's logger instance
    • state - The workflow's current state object 
    const 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');
    },
  },
});

@mastra/langfuse@1.0.0-beta.11

Minor Changes

  • 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: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
    • Braintrust: BRAINTRUST_API_KEY, BRAINTRUST_ENDPOINT
    • PostHog: POSTHOG_API_KEY, POSTHOG_HOST
    • Arize/Phoenix: ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
    • OTEL Providers:
      • Dash0: DASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASET
      • SigNoz: SIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINT
      • New Relic: NEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINT
      • Traceloop: TRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINT
      • Laminar: LMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_ID

    Example 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.

@mastra/mcp-docs-server@1.0.0-beta.21

Minor Changes

  • feat(mcp-docs-server): add embedded docs MCP tools (#11532)

    Adds 5 new MCP tools to read embedded documentation from installed @mastra/* packages:

    • listInstalledMastraPackages: Discover packages with embedded docs
    • readMastraSourceMap: Read export mappings from SOURCE_MAP.json
    • findMastraExport: Get type definitions and implementation for specific exports
    • readMastraEmbeddedDocs: Read topic documentation
    • searchMastraEmbeddedDocs: Search across all embedded docs

    These tools enable AI coding agents to understand Mastra packages by reading documentation directly from node_modules.

@mastra/otel-exporter@1.0.0-beta.12

Minor Changes

  • 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: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
    • Braintrust: BRAINTRUST_API_KEY, BRAINTRUST_ENDPOINT
    • PostHog: POSTHOG_API_KEY, POSTHOG_HOST
    • Arize/Phoenix: ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
    • OTEL Providers:
      • Dash0: DASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASET
      • SigNoz: SIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINT
      • New Relic: NEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINT
      • Traceloop: TRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINT
      • Laminar: LMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_ID

    Example 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.

@mastra/playground-ui@7.0.0-beta.21

Patch Changes

  • Replace deprecated client.getTraces with a client.listTraces (#11711)

  • Make initialState optional in studio (#11744)

@mastra/posthog@1.0.0-beta.11

Minor Changes

  • 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: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
    • Braintrust: BRAINTRUST_API_KEY, BRAINTRUST_ENDPOINT
    • PostHog: POSTHOG_API_KEY, POSTHOG_HOST
    • Arize/Phoenix: ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME, PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
    • OTEL Providers:
      • Dash0: DASH0_API_KEY, DASH0_ENDPOINT, DASH0_DATASET
      • SigNoz: SIGNOZ_API_KEY, SIGNOZ_REGION, SIGNOZ_ENDPOINT
      • New Relic: NEW_RELIC_LICENSE_KEY, NEW_RELIC_ENDPOINT
      • Traceloop: TRACELOOP_API_KEY, TRACELOOP_DESTINATION_ID, TRACELOOP_ENDPOINT
      • Laminar: LMNR_PROJECT_API_KEY, LAMINAR_ENDPOINT, LAMINAR_TEAM_ID

    Example 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.

@mastra/rag@2.0.0-beta.6

Patch Changes

  • Remove unnecessary 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)

@mastra/schema-compat@1.0.0-beta.6

Patch Changes

  • 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.

@mastra/server@1.0.0-beta.21

Patch Changes

  • 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:

    • Properly unwraps all layers of nested optional/nullable types (e.g., from .partial() on already-optional fields)
    • Ensures compatibility with both zod v3 and v4

create-mastra@1.0.0-beta.14

Patch Changes

  • Replace deprecated client.getTraces with a client.listTraces (#11711)

  • Make initialState optional in studio (#11744)

mastra@1.0.0-beta.14

Patch Changes

  • Replace deprecated client.getTraces with a client.listTraces (#11711)

  • Make initialState optional in studio (#11744)

Full Changelog: 8edb597

Check out latest releases or
releases around mastra-ai/mastra @mastra/core@1.0.0-beta.21

Don't miss a new mastra release

NewReleases is sending notifications on new releases.

Get notifications