Skip to content
Leverage AI Developer Support

Mastra

Mastra is the API app’s AI runtime. The repo uses one registered Mastra instance so agents, workflows, tools, storage, scorers, observability, and Studio inspection all share the same runtime boundary.

What It Owns

Section titled “What It Owns”
Mastra feature Repo use Benefit
Agents Public assistant, private research, planner, synthesis, guardrail classifier, evidence-intent classifier, and tabular SQL planner agents. Keeps specialized model behavior inspectable and testable instead of hiding everything in route handlers.
Workflows Assistant turn orchestration, private turn preparation, focus preparation, evidence prep, HITL prep, synthesis prep, and eval scenario workflows. Gives structured steps for predictable chat preparation and lets evals target workflow behavior directly.
Tools Canonical tools such as mail-live-query, contact-live-query, calendar-live-query, workspace-chat-live-query, work-item-live-query, file-resource-live-query, and connector-resource-list. Keeps provider-specific code behind domain tools so chat orchestration does not branch on provider names.
Memory Conversation history, thread persistence, branch cloning, and message deletion/repair paths. Makes transcript storage durable while letting the app enforce ownership and branch behavior around it.
Processors Chat-history invariant cleanup and selected-skill activation. Strips owner-visible reasoning from model replay and activates selected published skills without expanding permissions.
Skills / workspace storage Published skill versions are materialized as Mastra-compatible skill bundles. Runtime uses immutable published versions, not mutable drafts.
Vector stores Qdrant-backed research vectors registered on the app Mastra instance. Indexed connector points include vectors, extracted chunk text, and permission/provenance payloads. Keeps vector retrieval available from the same inspectable runtime and returns snippets without provider rehydration during synthesis.
Datasets and experiments Chat workflow, HITL, runtime smoke, queue interrupt, answer-quality, and private orchestration experiment lanes. Lets developers compare prompt/runtime changes through persisted Mastra datasets instead of one-off scripts.
Scorers Registered chat, private-orchestration, trace-scoring, and selected workflow-step live scorers. Encodes answer-quality, privacy, path, and outcome checks as repeatable release gates and Studio-visible workflow telemetry.
Observability and logging Pino logger plus Mastra observability with sensitive-data filtering. Keeps runtime traces and logs available for debugging while redacting sensitive fields.
Voice The exact-pinned AWS Nova Sonic adapter transcribes bounded private microphone audio without registering audio in Mastra observability. Reuses Mastra’s Bedrock bidirectional-stream implementation while the app owns privacy, auth, limits, and transcript filtering.
Server auth and API routes Better Auth provider, production Studio operator allowlist, user-isolation middleware, and connector API routes registered through Mastra server config. Keeps Mastra Studio and app API routes behind the same authenticated runtime boundary while production Studio/built-in Mastra routes stay operator-scoped.

Architecture Decision

Section titled “Architecture Decision”

Decision: keep one canonical app Mastra instance in apps/api.

  • The runtime remains Studio-visible: registered agents, workflows, tools, and scorers can be inspected instead of becoming route-local black boxes.
  • Product policy stays app-owned: Mastra runs the primitives, while auth, connector policy, privacy, and user-visible contracts stay in repo code and feature docs.
  • Production Studio access is explicit: when NODE_ENV=production, built-in Mastra/Studio routes require a Better Auth user id or email in MASTRA_STUDIO_OPERATOR_ALLOWLIST; app-owned custom API routes continue using their own authenticated web-user policy.
  • Production or customer-cluster Studio exposure is an operator/admin surface: keep Studio behind the app-owned allowlist plus operator-appropriate ingress or network controls, while local development can leave the allowlist empty for authenticated Better Auth users.
  • Connector tools stay domain-oriented: mail, contact, workspace chat, work-item, file document search, and resource-list behavior can add providers without leaking provider-specific tool ids into chat contracts.
  • Evals use the same registered runtime targets that production code uses where possible, which reduces drift between test fixtures and real orchestration.
Screenshot Placeholder
Mastra Studio runtime registry

Replace later with a screenshot showing registered agents, workflows, canonical live tools, and dataset experiments in Studio.

How To Upgrade

Section titled “How To Upgrade”

  1. Start with the installed Mastra docs/types/source in apps/api/node_modules/@mastra/*, then check Mastra MCP docs and migration guides for the target line.

  2. Upgrade the Mastra package family together in apps/api; do not mix major Mastra runtime/storage lines casually. The repo uses exact package pins, so bun update refreshes within the configured constraints and bun add <package>@latest is the explicit version-move path for packages that should advance:

    Terminal window
    # from apps/api
    bun update mastra @mastra/ai-sdk @mastra/auth-better-auth @mastra/clickhouse @mastra/core @mastra/evals @mastra/libsql @mastra/loggers @mastra/memory @mastra/mongodb @mastra/observability @mastra/qdrant @mastra/rag
    bun add @mastra/core@latest @mastra/memory@latest @mastra/clickhouse@latest
    bun add --exact @mastra/voice-aws-nova-sonic@0.2.0
    bun add -d mastra@latest

  3. If the web app’s Mastra client contract changes, update the client package too:

    Terminal window
    # from apps/web
    bun update @mastra/client-js
    bun add @mastra/client-js@latest

  4. Run mastra migrate only when the Mastra release notes or storage migration guide say a storage schema migration is required, and run it against the intended storage backend.

  5. Verify the API runtime:

    Terminal window
    bun run --cwd apps/api check-types
    bun run --cwd apps/api test
    bun run test:api:chat:runtime-smoke
    bun run test:api:chat:review

  6. Include bun run --cwd apps/api test:observability:clickhouse:smoke when storage, observability, or ClickHouse behavior changes.

Current Package State

Section titled “Current Package State”
  • apps/api/package.json, apps/web/package.json, and bun.lock are the current package-version sources of truth.
  • Speech to text pins @mastra/voice-aws-nova-sonic@0.2.0; do not use the compromised and unpublished 0.1.4 release.
  • The previous direct ollama-ai-provider-v2 dependency is not installed because the repo had no production imports and the latest provider line peers ai ^5 || ^6, not AI SDK v7.
  • Installed Mastra docs and types are available under apps/api/node_modules/@mastra/*/dist; prefer those for code work, then use Mastra website docs for latest conceptual guidance.

Upgrade Notes

Section titled “Upgrade Notes”
  • @mastra/core@1.47.0 makes AgentController the canonical replacement for the old Harness surface. Do not import @mastra/core/harness; it is a deprecated compatibility entrypoint. Test-only AgentController spike coverage should import from @mastra/core/agent-controller.
  • AgentController sessions require a valid Workspace instance in the current package line. Test fixtures that create sessions should use a local, contained Workspace rather than relying on the old implicit no-workspace path.
  • @mastra/core@1.47.0 adds AI SDK v7 / LanguageModelV4 support for language models, but Mastra Memory and RAG embedding inputs still accept older embedding contracts. Bedrock AI SDK v7 embedders must enter Mastra Memory/RAG through resolvePrivateBedrockMastraEmbeddingModel() until Mastra accepts v4 embedders directly.
  • Remove the temporary Bedrock embedding adapter as soon as installed Mastra Memory/RAG types accept AI SDK v4 embedding models directly and apps/api typecheck passes without the adapter.
  • @mastra/core@1.48.0 adds scheduled-agent Heartbeats, file-based agents/subagents, storage-backed suspended-run discovery for HITL, managed working memory extraction, and Inngest parity improvements. These are not production chat defaults; adopt them only with product policy, privacy review, and targeted eval coverage.
  • AI SDK v7 is ESM-only, uses the new provider v4 interfaces, has stricter stream/no-output behavior, and includes security fixes around downloads, tool approval, and prototype-pollution surfaces. Keep API/web callers on documented v7 helpers and verify runtime behavior before adopting new result/stream helpers.
  • AI SDK v7 exposes top-level reasoning support and stable telemetry APIs. Chat stream calls now attach API-owned safe-summary telemetry with input/output recording disabled and runtime/tool context excluded by default; the summaries may include reasoning-token counts, finish reasons, tool names/outcomes, durations, and token counts only.
  • Mastra 1.48.0 still consumes redacted per-call telemetry settings through experimental_telemetry and invokes older stream callback aliases in the current bridge. Keep the combined telemetry/callback adapter isolated to the chat telemetry policy and remove it when installed Mastra exposes stable AI SDK telemetry, onEnd, onToolExecutionEnd, and onStepEnd names end-to-end.
  • Mastra Studio agent metadata inspection may show the non-executing leverage/studio-inspection-only model for app-owned agents. That model is only for Studio introspection with an otherwise empty Studio request context; real chat and eval execution still require the app-owned model policy context and fail closed without it.

Deferred Mastra Candidates

Section titled “Deferred Mastra Candidates”
  • Agent Signals remains deferred until a spike proves queue interruption, HITL information-request behavior, dropped UI messages, multi-tab stream behavior, and file/image preservation.
  • A2AAgent remains deferred until signed/verified cards, allowlisted endpoints, service auth or mTLS, egress controls, callbacks, and customer-boundary docs are accepted.
  • ResponseCache remains limited to deterministic classifier, guardrail, or suggested-prompt calls with tenant/resource scoped keys and TTLs. Do not use it as a general private-chat response cache.
  • Mastra protected-route FGA deny/error mode remains deferred until tests prove all protected routes have explicit resource mappings and service-auth routes are intentionally exempt with requiresAuth: false.

Current Limits

Section titled “Current Limits”
  • Workflow registrations now use canonical workflow-id keys directly; the old workflow registration shim was removed after the installed Mastra package proved raw committed workflows work for dataset workflow-target experiments.
  • Selected private preparation, evidence preparation, and live-evidence workflow steps now attach live scorers through createStep({ scorers }). Other CI, experiment, and trace scorers remain Studio-visible through the global scorer registry and may still appear unattached when they are not runtime step scorers.
  • Background tasks are configured, but current production agents keep private orchestration on the foreground path so model-level background overrides do not bypass app policy.
  • Mastra public API wins over internal-only types or runtime observations. If a capability is not in the published docs/reference, stop before adopting it by default.

Canonical Sources

Section titled “Canonical Sources”
  • apps/api/src/mastra/index.ts
  • apps/api/src/mastra/runtimeStorage.ts
  • apps/api/src/mastra/workflows/registeredMastraWorkflows.ts
  • apps/api/src/mastra/tools/canonicalLiveTools.ts
  • apps/api/src/mastra/scorers/registeredMastraScorers.ts
  • apps/api/src/mastra/processors/chatHistoryInvariantProcessor.ts
  • apps/api/src/mastra/processors/selectedChatSkillsProcessor.ts
  • docs/features/chat/spec.md
  • docs/features/live-query/spec.md
  • docs/features/human-in-loop/spec.md
  • docs/features/skills/spec.md
  • docs/features/speech-to-text/spec.md

Official Docs

Section titled “Official Docs”