Skip to main content

Shared Platform Tools

Base Platform Tools Overview​

The Base Platform provides shared tools and utilities that are reused across K12, TAP, and Reasoning Engine workloads. These include Azure service integrations, content safety, and common helper functions.

Azure Service Integrations​

Azure AI Inference Provider​

The Azure AI Inference provider integration enables all workloads to use tenant-hosted model deployments (typically Azure AI Foundry deployments).

  • Code: src/mastra/providers/azure-ai-inference.ts
  • Purpose: Azure AI Inference provider integration for LLM access
  • Configuration: Model deployments, endpoints, and API versions
  • Features:
    • Multiple model deployment support
    • Automatic retry logic
    • Token usage tracking
    • Model capability detection

Azure Content Safety​

Content moderation service for analyzing text and images.

  • Code: src/mastra/providers/azure-content-safety.ts
  • Purpose: Multi-modal content moderation (text, images)
  • Features:
    • Severity threshold configuration
    • Category filtering (Hate, Violence, Sexual, Self-Harm)
    • Custom blocklist support
    • Batch processing support

Used by:

  • TAP workflows for content moderation
  • Admin tools for blocklist management

Agent Utilities​

Agent Factory Patterns​

Common patterns for creating and configuring agents across workloads.

  • Code: src/mastra/agents/
  • Patterns:
    • Memory Agents - Agents with conversation history
    • Recovered Agents - Legacy adapter agents
    • Multimodal Agents - Agents supporting image/text input

Profile Service​

Database-driven agent configuration service.

  • Code: Agent profile loading and caching logic
  • Purpose: Load agent prompts and LLM overrides from Core.AgentProfiles
  • Features:
    • Profile hash-based caching
    • Automatic rebuild on profile changes
    • Version history tracking

For detailed information, see Agent Prompt Overrides.

MCP Server Tools​

Tools exposed via Model Context Protocol servers for external access.

Admin MCP Server​

Operational tools for managing agent profiles and system health.

  • Server: src/mastra/mcp-servers/admin-server.ts
  • Tools: packages/platform-runtime/src/tools/admin/

Available Tools:

  • admin-update-agent-profile - Update agent prompts and configurations
  • admin-list-agent-profiles - List current agent profiles
  • admin-agent-profile-history - View agent profile version history
  • admin-db-health-check - Database connectivity and health checks

For complete documentation, see Admin Tools.

Documentation MCP Server​

Searchable access to the Docusaurus documentation corpus (~196 pages). Enables agents and IDE sessions to query project documentation programmatically.

  • Server: src/mastra/mcp-servers/docs-server.ts
  • Tools: src/mastra/tools/docs/
  • Skip flag: MASTRA_SKIP_DOCS_MCP=true

Available Tools:

  • docs-search - Full-text search with ranked results and snippets
  • docs-get-page - Fetch full page content by ID, with suggestions on miss
  • docs-list-pages - Browse documentation tree with domain/category filters

IDE integration: Configure a local MCP client entry for the mastra-project-docs stdio server.

Web Search Integration​

Tavily Search Tool​

Platform-level web search tool powered by Tavily API.

  • Code: src/mastra/tools/base/tavily-search.tool.ts
  • Tool ID: base-tavily-search
  • Purpose: Real-time web search with AI-generated summaries and relevance scoring
  • Features:
    • Search depth control (basic/advanced)
    • Topic filtering (general/news/finance)
    • Domain inclusion/exclusion
    • AI-generated answer summaries
    • Follow-up question suggestions
    • Image search support
    • Time-based filtering for news

Input Parameters:

{
  query: string,              // Search query
  searchDepth?: 'basic' | 'advanced',
  topic?: 'general' | 'news' | 'finance',
  maxResults?: number,        // Default 5
  includeDomains?: string[],  // Whitelist domains
  excludeDomains?: string[],  // Blacklist domains
  includeAnswer?: boolean,    // AI-generated summary
  includeImages?: boolean,    // Include image results
  days?: number              // News recency filter
}

Output Structure:

{
  success: boolean,
  query: string,
  answer?: string,           // AI-generated summary
  results: Array<{
    title: string,
    url: string,
    content: string,
    score: number,           // Relevance 0-1
    publishedDate?: string
  }>,
  images?: string[],
  followUpQuestions?: string[],
  responseTime: number,      // ms
  resultCount: number,
  error?: string
}

Used by:

  • Admin diagnostic tools (admin-test-tavily-search)
  • Legacy workflows requiring domain filtering

For provider details, see Tavily Search Provider.

Perplexity Search Tool​

Primary web search solution for the Mastra platform, especially the Reasoning Engine.

  • Code: src/mastra/tools/base/perplexity-search.tool.ts
  • Tool ID: base-perplexity-search
  • Purpose: AI-powered web search with automatic synthesis and citation tracking
  • Features:
    • Single API call for search + synthesis
    • Multiple search modes (internet, academic, news, youtube, reddit)
    • Intelligent model selection (sonar/sonar-pro)
    • Automatic citation extraction with URL fallback
    • Default system prompt optimized for inline citations
    • Query-specific parameter generation (model, searchMode)

Input Parameters:

{
  query: string,                      // Search query
  model?: 'sonar' | 'sonar-pro',     // Model selection
  searchMode?: 'internet' | 'academic' | 'news' | 'youtube' | 'reddit',
  maxTokens?: number,                // Max response tokens
  temperature?: number,              // 0.0-2.0
  returnCitations?: boolean,         // Default true
  systemPrompt?: string              // Override default prompt
}

Output Structure:

{
  success: boolean,
  answer: string,                    // Synthesized answer
  citations: string[],               // Extracted URLs
  detailedCitations?: Array<{        // Structured citations
    number: number,
    url: string,
    title?: string
  }>,
  model: string,
  responseTime: number,              // ms
  usage: {
    promptTokens: number,
    completionTokens: number,
    totalTokens: number
  },
  error?: string
}

Used by:

  • Reasoning Engine domain retrieval step (primary search solution)
  • Query generator agent workflow
  • Any workflow requiring AI-synthesized search results

For complete documentation, see Perplexity Search.

Persistence​

Optional LibSQL Store​

Some agents include optional persistence examples using LibSQLStore.

  • Location: src/mastra/ (various agent implementations)
  • Note: Persistence is configurable and does not require a local .mastra database by default
  • Use Cases:
    • Agent conversation history
    • Workflow state persistence
    • Tool execution logs

Workload-Specific Tools​

For tools specific to each workload, see:

K12 Tools

EOP and QRG generation tools

TAP Tools

Image captioning and tagging tools

Admin Tools

Operational and management tools

Code Organization​

How to Read the Code​

  1. Start with: apps/runtime/src/mastra-runtime.ts to see how providers and tools are wired at startup
  2. MCP Tools: Tools exported to MCP are in src/mastra/tools/ and registered in mcp-servers/
  3. Agent Factories: Agent creation patterns in src/mastra/agents/
  4. Providers: Azure service integrations in src/mastra/providers/

Key Directories​

  • src/mastra/agents/ - Agent factory patterns and base implementations
  • src/mastra/providers/ - Azure service provider integrations
  • src/mastra/tools/ - Reusable tools (admin, TAP API, etc.)
  • src/mastra/mcp-servers/ - MCP server definitions
  • src/mastra/workflows/ - Workflow definitions (K12, TAP, Reasoning)

Testing​

Use repository search to find tests and examples:

  • Search pattern: File names in src/mastra/tools/, src/mastra/providers/, etc.
  • Test locations: tests/admin/, packages/domain-k12/tests/, packages/domain-tap/tests/, tests/tap/
  • Example scripts: scripts/ directory

Next Steps​

Base Platform Introduction

Overview of the Base Platform

Agent Framework

Agent patterns and configuration

Admin Tools

Operational tools documentation

Database: Core

Core schema and tables