Skip to content

Mastra Agents And Tools

Last refreshed: 2026-07-28

Runtime

The Mastra runtime is src/mastra/runtime.ts. It uses PostgresStore with DATABASE_URI, registers one primary workflow, registers agents, and exposes ensureMastraStorageReady.

Mastra API assumptions must be verified against installed docs or the repo-local skill before code changes.

Registered Agents

  • anuvaxTextAgent: general Anuva text agent.
  • intentAgent: creates a video description brief.
  • knowledgeAgent: decides source usage and knowledge context strategy.
  • narrativeAgent: generates narrative scenes.
  • visualAgent: creates visual strategy.
  • presentationNarrativeAnalystAgent: analyzes narrative for slide planning.
  • presentationSlidePlannerAgent: produces slide plan.
  • directorAgent: refines camera direction.
  • editAgent: handles edit-oriented agent contracts.

Agent definitions and deterministic responsibility boundaries are documented in src/mastra/agents/presentationvideo-agent-contracts.ts.

Workflows

  • presentationVideoWorkflow: master generation workflow.
  • ragWorkflow: source planning and context collection.
  • narrativeWorkflow: scene generation and normalization.
  • visualsWorkflow: visual strategy generation.
  • slidesWorkflow: narrative analysis and typed Main, Companion, and Emphasis planning.
  • directionWorkflow: deterministic direction plus optional refinement.

Canonical workflow IDs are in src/lib/anuva/workflow-graph.ts.

flowchart TD
  master["🎬 presentationVideoWorkflow"] --> rag["📚 ragWorkflow"]
  master --> narrative["📝 narrativeWorkflow"]
  master --> visuals["🎨 visualsWorkflow"]
  master --> slides["🖥️ slidesWorkflow"]
  master --> direction["🎥 directionWorkflow"]

  rag --> knowledgeAgent["knowledgeAgent"]
  narrative --> narrativeAgent["narrativeAgent"]
  visuals --> visualAgent["visualAgent"]
  slides --> analyst["presentationNarrativeAnalystAgent"]
  slides --> planner["presentationSlidePlannerAgent"]
  direction --> director["directorAgent"]

Tools

Tool groups:

  • src/mastra/tools/presentation: run preparation, persisted RAG context, scene persistence, visual assignment, immutable compilation revisions, generation job creation.
  • src/mastra/tools/compiler: scene normalization, enrichment, timing, direction, and config compilation.
  • src/mastra/tools/media: asset library, semantic asset search, TTS.
  • src/mastra/tools/rag: document loading, chunking, embedding, saving, retrieval.
  • src/mastra/tools/web: web search, website scrape, RSS parse.
  • src/mastra/tools/validation: slide validation and presentation save handoff.

Code-owned prompt builders live alongside the owning tool groups:

  • src/mastra/tools/presentation/prompt-builders.ts: setup brief, compatibility voiceover generation, per-scene edit/image prompts, and generated-image fallback prompts.
  • src/mastra/tools/rag/prompt-builders.ts: RAG image context and video section refinement prompts.
flowchart LR
  actions["Server actions"] --> builders["Code prompt builders"]
  builders --> edit["editAgent"]
  builders --> visual["visualAgent"]
  builders --> text["anuvaxTextAgent"]
  workflow["presentationVideoWorkflow"] --> agents["Workflow agents"]
  agents --> payload["Payload state + ai_interactions"]
  edit --> payload
  visual --> payload
  text --> payload

Model Configuration

Shared model constants live in src/lib/ai/model-config.ts.

Current constants include:

  • OpenAI text generation: gpt-5.6-terra.
  • OpenAI web search: gpt-5.6-terra.
  • OpenAI embeddings: text-embedding-3-small.
  • OpenAI image generation: gpt-image-2-2026-04-21.
  • ElevenLabs TTS: eleven_v3.

Before changing model strings, run:

node .agents/skills/mastra/scripts/provider-registry.mjs --list
node .agents/skills/mastra/scripts/provider-registry.mjs --provider openai

Memory And Metering

Presentation video memory helpers live in src/mastra/memory/presentationvideo.memory.ts.

Metered agent execution uses src/mastra/utils/metered-agent-step.ts and writes AI interaction records through src/lib/coins/metering.ts. Metering metadata should keep workflow ID, run ID, step ID, provider, model, and action name explicit.

Deterministic Boundaries

Validation, normalization, compilation, stage gate handling, edit-impact planning, and retry policy live in src/lib/anuva, src/lib/presentation-config, and Mastra tools. Agents decide surface intent and complementary content. Deterministic code owns IDs, asset references, fragment ordering, absolute timeline events, Bento normalization, compatibility evaluation, and persistence. Keep free-form agent output behind sceneSurfacePlanSchema and the workflow schemas.

Bento Authoring Assistant

generateBentoAiOperationsAction uses the installed Mastra structured-output API with editAgent. src/lib/bento/ai-operations.ts owns the prompt and closed intent schema. Server code binds model intents to the authenticated actor, expected revision, selected slide/surface, allowlisted assets and layouts, then validates final operations with validateAnuvaEditorOperation.

The editor receives one reviewed atomic operation batch and owns preflight and composite undo. Metering uses presentationBentoEdit; audit records retain digests and operation identities, not raw prompts, raw responses, secrets, or binary content.