Skip to content

Mastra Agents And Tools

Last refreshed: 2026-05-19

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: slide analysis, planning, and Reveal markup generation.
  • 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, compilation snapshots, 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.4-2026-03-05.
  • OpenAI web search: gpt-5.4.
  • 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 and Mastra tools. Keep free-form agent output behind schemas and deterministic normalization.