Skip to main content

Base Platform

Base Platform Overview​

The Base Platform is the shared infrastructure layer that powers both K12 and TAP applications. It provides centralized LLM provider management, database-driven agent configuration, and common utilities that ensure consistent behavior across all workloads.

What Is Currently Implemented​

The Base Platform delivers production-ready components:

1. LLM Provider Infrastructure​

Azure AI Inference Integration — Production deployment uses tenant-hosted model deployments (typically Azure AI Foundry deployments) via the Azure AI Inference provider. The provider handles:

  • Model selection and routing based on agent requirements
  • Token usage tracking and cost monitoring
  • Retry logic with exponential backoff for transient failures
  • Managed Identity authentication for secure, keyless access

Embedding Generation — Not currently implemented in this repository.

2. Database-Driven Agent Configuration​

Prompt Override System — All AI agents load their prompts, temperature settings, and model preferences from the Core.AgentProfiles SQL table rather than code. This enables:

  • Instant prompt updates without redeployment
  • A/B testing different agent configurations in production
  • Complete audit trail of all prompt changes with timestamps
  • Rollback capability to previous agent versions

Currently Active: 15+ agent profiles across K12 (EOP editors, QRG generators, category classifiers) and TAP (image captioning, content safety analyzers).

3. Azure Content Safety Integration​

Multi-Modal Moderation — Shared provider for analyzing both text and images:

  • Detects hate speech, violence, self-harm, and sexual content
  • Custom severity thresholds per category
  • Blocklist support for domain-specific terms
  • Currently used by TAP for content moderation

4. Common Administrative Tools​

Agent Profile Management — API endpoints and tools for:

  • Creating/updating agent profiles via the database
  • Bulk prompt imports from JSON files
  • Health checks that verify all agents have valid profiles
  • Validation of LLM parameter constraints (temperature, max_tokens)

Database Utilities — Shared SQL client helpers, connection pooling, and query logging used by all workflows.

Architecture Components​

Tools​

The Base Platform provides common tools used across all workloads:

  • Azure Content Safety - Multi-modal content moderation for text and images
  • Database Utilities - SQL client helpers and connection management
  • Logging Tools - Centralized logging and monitoring utilities
  • Admin Tools - Agent profile management and system configuration

For complete tool catalog including usage examples and code locations, see Base Platform Tools.

Agents​

All agents in the Mastra framework use the Base Platform's agent system:

  • Profile-Based Configuration - Agent prompts and settings managed in Core.AgentProfiles database table
  • Runtime Overrides - Update agent behavior without code deployment
  • Versioning System - Complete audit trail of agent configuration changes
  • Caching - Efficient profile loading with hash-based invalidation
  • Standardized Export Pattern - Every agent exports 5 functions: getXAgent() (cached getter), getXAgentFactory() (factory accessor), buildXAgentFresh() (cache bypass), invalidateXAgentCache() (force rebuild), and configureXAgent() (dependency injection)
  • Factory System - IAgentFactory interface providing getAgent(), buildFresh(), and invalidateCache() methods with automatic model validation and profile hash-based cache invalidation

For detailed agent documentation including registry IDs and profile management, see Agents (Detailed) (/agents/detailed).

For information on how agent prompt overrides work, see Agent Prompt Overrides.

For the complete standardized export pattern and usage examples, see Unified Agent Platform.

Database Core​

The Core schema provides shared infrastructure:

  • AgentProfiles - Versioned agent configurations with system prompts and LLM overrides
  • LLMParamsDim - LLM parameter presets and defaults
  • LLMModelCapabilities - Model capability tracking for deployment planning
  • Azure Resource Dimensions - AI Search, Content Safety, Form Recognizer resource tracking

For schema details and ER diagrams, see Database: Core.

Azure Providers​

Integrated Azure service providers:

  • Azure AI Inference - LLM provider with model deployment resolution and token tracking
  • Azure Content Safety - Text and image moderation with blocklist support
  • Voice Provider - NoopVoice stub implementation providing placeholder TTS/STT responses to prevent "No voice provider configured" errors during development

For Azure service configuration and authentication, see Azure Integration.

External Providers​

Third-party service integrations:

  • Tavily Search - Real-time web search for AI agents and RAG patterns, with domain filtering, news/finance topics, and AI-generated answer summaries
  • Perplexity Search - Alternate web search provider implementation (when enabled)

For web search configuration and usage, see Tavily Search Provider (#tavily-search-provider).

Tavily Search Provider​

The Tavily Search provider enables real-time web retrieval for agents and workflows that need current information beyond the knowledge base.

Features:

  • Fast web search (~300-500ms) optimized for AI agent consumption
  • Domain filtering (include/exclude specific sites)
  • Topic-focused searches (general, news, finance)
  • AI-generated answer summaries with source citations
  • Automatic retry with exponential backoff

Environment Variables:

TAVILY_API_KEY=tvly-your-api-key       # Required: Get from https://tavily.com
TAVILY_DEFAULT_SEARCH_DEPTH=basic      # Optional: 'basic' (fast) or 'advanced' (thorough)
TAVILY_DEFAULT_MAX_RESULTS=5           # Optional: 1-20 results
TAVILY_TIMEOUT_MS=30000                # Optional: Request timeout
TAVILY_DEBUG_TIMINGS=false             # Optional: Enable debug logging

Usage:

import { tavilySearch, domainSearch, newsSearch } from '../providers/tavily-search.ts';

// Basic search
const results = await tavilySearch({
  query: 'latest quantum computing breakthroughs',
  maxResults: 5,
  includeAnswer: true,
});

// Domain-filtered search (academic sources only)
const academic = await domainSearch(
  'machine learning best practices',
  ['arxiv.org', 'papers.nips.cc'],
  10
);

// News search (recent content)
const news = await newsSearch('AI regulation updates', 7); // last 7 days

Code Location: src/mastra/providers/tavily-search.ts

How It Works​

The Base Platform serves as the foundation layer:

  1. Initialization - Services bootstrap core infrastructure (database schema, agent profiles)
  2. Agent Configuration - Agent group configuration functions (e.g., configureQrgAgents()) called to inject dependencies before agent creation
  3. Configuration Loading - Agents and tools load their configurations from the database
  4. Provider Integration - Azure services authenticate and connect using Managed Identity or keys
  5. Cross-Workload Sharing - K12, TAP, and Reasoning Engine workloads use shared components

This architecture ensures consistency, reduces duplication, and enables centralized management of common functionality.

Important: Some agent groups (QRG, etc.) require calling their configureXAgents() function before calling getXAgent() to inject required dependencies like model instances.

Key Features​

  • Database-Driven Configuration - Agent prompts and settings live in the database for runtime updates
  • Managed Identity Support - Secure authentication for Azure services without embedded keys
  • Versioned Agent Profiles - Complete audit trail with rollback capabilities
  • Shared Tool Registry - Common tools available across all workloads
  • MCP Server Exposure - Tools accessible via Model Context Protocol

For detailed feature documentation, see Agent Prompt Overrides.

Development & Testing​

  • Code Locations: Core components in src/mastra/
  • Tools: Shared tools in src/mastra/tools/
  • Agents: Agent framework in src/mastra/agents/
  • Providers: Azure integrations in src/mastra/providers/
  • Database: Core schema in db/sqlproj/Mastra.Platform.CoreDb/
  • Tests: Unit tests distributed across workload test directories

For development setup and best practices, see Development Guide.

Next Steps​

Base Platform Tools

Explore shared tools and utilities

Agents Overview

Learn about the agent framework

Agent Prompt Overrides

Understand how agent configuration works

Database Core

Core schema and tables