DOCSEARCHbyAlgolia
Submit Docs

Mastra AI Orchestration Framework

repository·main·Indexed 30 days ago

https://github.com/mastra-ai/mastra

An orchestration framework designed to decouple decision-making from code execution for durable, scalable agentic workflows. Includes provider-based systems for storage, sandboxes, and browsers, with specialized SDK integrations for ACP (Agent Client Protocol), Claude, Cursor, and OpenAI agents.

Tokens
2M
Snippets
5.3K
Records
9.2K
Agent score
97%

What's inside mastra-ai/mastra

  1. Overview of @mastra/voyageai capabilities

    main

    The @mastra/voyageai package provides integration for VoyageAI services, including:

    • Text Embeddings: Supports voyage-4 and voyage-3 series, including specialized models for code, finance, and law. Includes token-aware batching via the tokenize() method.
    • Multimodal Embeddings: Supports text, images, and video via voyage-multimodal-3 and voyage-multimodal-3.5.
    • Contextualized Chunk Embeddings: Via voyage-context-3 and voyage-context-4.
    • Rerankers: Supports rerank-2.5 and rerank-2 families, implementing the RelevanceScoreProvider interface.

  2. Overview of the Mastra platform products

    main

    The Mastra platform provides three core products for deploying, monitoring, and managing AI applications built with the Mastra framework:

    • Observability: Provides searchable traces, logs, and metrics across all Mastra projects and deployments. This is the baseline product for every project.
    • Studio: A hosted visual environment for testing agents, running workflows, and inspecting traces. Using Studio automatically includes Observability.
    • Server: A production deployment target that runs your Mastra application as an API server. Using Server automatically includes Observability.

    Projects are organized under an Organization (the multi-tenant container for your team). A single project can utilize Observability, Studio, and Server simultaneously.

  3. Overview of Mastra Observability

    main

    Mastra's observability system provides visibility into agent runs, workflow steps, tool calls, and model interactions. It captures several complementary signals that work together:

    • Tracing: Records operations as a hierarchical timeline of spans (inputs, outputs, token usage, timing).
    • Logging: Forwards structured logs (e.g., logger.info()) and automatically correlates them to traces via trace and span IDs.
    • Metrics: Automatically extracts duration, token usage, and cost data from traces without additional instrumentation.
    • Feedback: Stores human review signals (ratings, comments, corrections) linked to specific traces and spans.

    These signals share correlation IDs (trace ID, span ID, entity type, entity name), allowing you to navigate between metric spikes, traces, logs, and feedback.

  5. Overview of @mastra/agent-builder

    main
    @mastra/agent-builder is a package designed for programmatically building and managing Mastra agents. It features intelligent template merging capabilities, including automated dependency resolution, file conflict handling, and validation. It is currently marked as an experimental package.

  6. Overview of Mastra core capabilities

    main

    Mastra is a TypeScript framework designed for building production-ready AI applications. Key features include:

    • Model Routing: A standard interface to connect to 40+ providers (OpenAI, Anthropic, Gemini, etc.).
    • Agents: Autonomous entities that use LLMs and tools to solve tasks through reasoning and iteration.
    • Workflows: A graph-based engine for orchestrating complex, multi-step processes using syntax like .then(), .branch(), and .parallel().
    • Human-in-the-loop: Ability to suspend agents or workflows to await user approval or input, using storage to persist execution state.
    • Context Management: Tools for managing conversation history, RAG (Retrieval-Augmented Generation) from APIs/databases/files, and Observational Memory.
    • MCP Servers: Support for authoring Model Context Protocol servers to expose agents and tools to other compatible systems.
    • Production Tools: Built-in capabilities for evals (evaluations) and observability to refine agent performance.

  7. Overview of Mastra AI Agent Framework

    main

    Mastra is an open-source AI Agent Framework for TypeScript designed to provide the core primitives required for AI engineering. It allows developers to build, test, and deploy modular and extensible AI agents.

    Key capabilities include:

    • Agents: Equipped with tools, memory, and tracing capabilities.
    • Workflows: Managed via state-machine based logic.
    • Evals: Built-in evaluation tools for tracking and measuring AI output quality.
    • Storage: Dedicated storage solutions for RAG (Retrieval-Augmented Generation) pipelines.
    • Local Development: A playground environment for local testing and development.

  8. Overview of Scorers in Mastra

    main

    Scorers are automated tests used to evaluate non-deterministic AI outputs by providing quantifiable metrics (typically numerical values between 0 and 1). They allow you to measure agent quality using model-graded, rule-based, and statistical methods.

    Scorers can be used for:

    • Live evaluations: Running asynchronously in the background during real-time agent or workflow execution.
    • Trace evaluations: Evaluating historical traces from past interactions (requires observability to be configured).
    • CI/CD integration: Testing and monitoring agents as part of your deployment pipeline.

    Common types include Textual Scorers (accuracy, reliability), Classification Scorers (categorization accuracy), and Prompt Engineering Scorers (instruction impact).

  9. Overview of Mastra Browser Providers

    main

    Mastra enables agents to navigate websites, interact with elements, fill forms, and extract data through several browser providers. When you assign a browser instance to an agent, the provider's tools are automatically added to the agent's toolset.

    Available Providers

    • AgentBrowser (@mastra/agent-browser): Playwright-based with accessibility-first element targeting. Best for general web automation and scraping.
    • Stagehand (@mastra/stagehand): Browserbase provider with AI-powered element detection. Best for complex interactions using natural language selectors.
    • FirecrawlBrowser (@mastra/browser-firecrawl): Runs AgentBrowser tools against hosted Firecrawl Browser Sandbox sessions. Best for avoiding local browser infrastructure management.
    • BrowserViewer (@mastra/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools (like agent-browser, browser-use, or browse). Best for workspace agents driven via shell commands.

  10. Overview of @mastra/core components

    main

    The @mastra/core package provides the following core components for building AI-powered applications:

    • Mastra (/mastra): The central orchestration class that initializes and coordinates all components (agents, workflows, tools, memory, etc.) via a unified configuration interface.
    • Agents (/agent): Autonomous AI entities that encapsulate LLM interactions, conversation history, tool execution, and memory.
    • Workflows (/workflows): A graph-based execution engine for chaining, branching, and parallelizing LLM calls with state management and error recovery.
    • Tools (/tools): Functions with schemas and descriptions that agents can invoke to interact with external systems.
    • Memory (/memory): Thread-based conversation persistence providing semantic recall and working memory.
    • MCP (/mcp): Model Context Protocol integration for external tool sources (supports SSE, HTTP, and Hono-based servers).
    • Observability: Type-safe system for tracking AI operations through spans (full features available in @mastra/observability).
    • Storage (/storage): Pluggable storage layer for persisting agent data, memory, and workflow state (supports PostgreSQL, LibSQL, MongoDB, etc.).
    • Vector (/vector): Unified interface for vector stores, embedding management, and semantic search.
    • Server (/server): HTTP server implementation built on Hono with OpenAPI support for deploying Mastra as a standalone service.
    • Voice (/voice): Text-to-speech (TTS) and speech-to-text (STT) integration for voice interactions.
    • Browser (/browser): Utilities and base classes (like MastraBrowser) for browser automation.

  11. Identify required environment variables for model providers

    main

    Mastra uses specific environment variables to authenticate and configure different model providers and gateways. When setting up a model provider (such as OpenAI, Anthropic, or a gateway), you must ensure the corresponding environment variables are present in your runtime environment.

    Refer to the model router documentation to identify which provider you are using and the specific keys required for that provider.

  12. Understand the Embedded Pricing Model for `@mastra/observability`

    main

    The @mastra/observability package uses an embedded pricing snapshot for v0 runtime cost estimation. This model is a minified JSONL artifact used to estimate costs based on provider and model identifiers.

    Key Characteristics

    • Scope: Covers token pricing (input, output, cache, audio, and reasoning tokens) for specific provider + model combinations.
    • Tiers: Supports prompt-threshold pricing (e.g., when total_input_tokens > 200000).
    • Runtime Behavior:
      • Matches by canonical provider + model.
      • Uses the default tier unless a prompt-threshold condition matches.
      • Persists estimatedCost, costUnit, and costing metadata to token metric rows.
      • If a lookup fails, it attaches costing error metadata to the emitted usage payload.

    Note: This file is optimized for shipping size. Do not edit this file directly to add data; use the upstream costing pipeline for authoritative pricing updates.