AI Orchestration (Mastra)
Relevant source files
The following files were used as context for generating this wiki page:
The mdeapp uses Mastra as its primary agent runtime and orchestration layer. It serves as the bridge between the AI chat shell (CopilotKit) and the underlying models, primarily Gemini 3.5 Flash. Mastra manages agents, complex multi-step workflows, and specialized AI quality scorers to facilitate discovery and ticketing services for Medellín.
Sources: README.md:1-15, src/tests/smoke.test.ts:63-73
Core Architecture
The Mastra instance is the central configuration point where agents, workflows, scorers, and storage are registered. It utilizes a ConsoleLogger with configurable log levels and custom storage solutions (Postgres or LibSQL) to maintain persistence across runs.
The diagram shows how the Mastra runtime centralizes application logic between the user interface and the AI models.
Sources: src/mastra/index.ts:20-41, README.md:16-25
Registered Agents
The system employs a multi-agent architecture where specific agents are responsible for different domains of the platform.
| Agent Name | Functionality | Model |
|---|---|---|
pingAgent | Proves wiring between CopilotKit and Mastra. | Gemini 3.5 Flash |
routerAgent | Routes user queries to appropriate specialized agents. | Gemini 3.5 Flash |
rentalAgent | Handles apartment and short-term rental discovery. | Gemini 3.5 Flash |
conciergeAgent | General assistant for discovery and help. | Gemini 3.5 Flash |
eventAgent | Discovery and information regarding local events. | Gemini 3.5 Flash |
hostEventAgent | Specialized flow for users hosting events (Roberto). | Gemini 3.5 Flash |
evaluationAgent | Internal agent for assessing AI performance and quality. | Gemini 3.5 Flash |
Sources: src/mastra/index.ts:21-29, src/tests/smoke.test.ts:16-30, src/tests/smoke.test.ts:63-73
Workflow Management
Workflows in Mastra allow for deterministic, multi-step operations. For example, the eventDiscoveryWorkflow chains searching for events in Supabase with formatting them into UI-friendly cards.
Workflow Example: Event Discovery
The eventDiscoveryWorkflow consists of two primary steps:
- search-events: Calls
searchEventstool to query the database based on category, neighborhood, and price. - format-event-cards: Processes raw event data into standardized card objects for the frontend.
This flow illustrates the sequential processing of data from a raw query to a formatted UI response.
Sources: src/mastra/workflows/event-discovery-workflow.ts:40-100
AI Quality and Scorers
Mastra includes a scoring system to evaluate the quality of agent responses. A key implementation is the faithfulnessScorer, which detects hallucinations by comparing agent replies against the actual tool outputs.
Faithfulness Scoring Pipeline
The faithfulness scorer follows a defined lifecycle:
- Preprocess: Extracts claims (entities, prices, IDs) from the agent reply and identifies which ones are heuristically unsupported by tool data.
- Analyze: Uses a Gemini-based "judge" to confirm if unsupported claims are genuinely fabricated or just paraphrased.
- Generate Score: Calculates a numerical score (0.0 to 1.0) based on the ratio of grounded claims.
- Generate Reason: Provides a technical explanation of the score, citing specific unsupported claims.
Sources: src/mastra/scorers/faithfulness.ts:103-149, src/app/api/scorers/route.ts:12-25
Telemetry and Auditing
The system tracks "Turn Telemetry" to monitor performance and tool usage. Telemetry data is stored in the ai_runs table in Supabase, capturing metadata about every interaction.
| Field | Description |
|---|---|
telemetry_version | Current schema version (e.g., "1"). |
agent_map_key | The identifier of the agent that handled the turn. |
turn_status | Status of the turn (e.g., "success", "error"). |
slowest_tool | The tool call that took the longest duration. |
total_tokens | Combined input and output token count for the turn. |
Sources: src/mastra/lib/mastra-telemetry.test.ts:31-64, src/lib/supabase/database.types.ts:44-67
Workspace and Skills
The Mastra instance operates within a workspace that contains pre-defined "skills." These are organized into directories like mde-prompt-qa and mde-rental-quality. For security, the workspace tools config explicitly disables mutation operations like WRITE_FILE or DELETE on the filesystem.
Sources: src/mastra/workspaces.test.ts:10-40
Conclusion
The Mastra orchestration layer is the "brain" of the mdeapp, coordinating various specialized agents and deterministic workflows. By integrating robust telemetry, structured workspaces, and automated hallucination detection via scorers, it ensures that the AI-first discovery platform remains reliable, performant, and grounded in real-world data from the Medellín ecosystem.