Core Mastra Agents (Concierge & Router)
Relevant source files
The following files were used as context for generating this wiki page:
The Core Mastra Agents represent the intelligence layer of the mdeAI platform, providing a chat-first discovery experience for Medellín. The system is architected around two primary roles: the Router Agent, which acts as a lean dispatcher for specific workflows, and the Concierge Agent, which serves as the persistent, high-context interface for user interactions involving rentals, events, and local points of interest.
These agents are powered by the Gemini 3.5 Flash model and integrated via the Mastra framework. While the Router focuses on high-level intent classification and workflow triggering, the Concierge manages complex working memory, neighborhood intelligence, and multi-tool orchestration to provide a seamless "local friend" experience.
Sources: README.md:1-20, src/mastra/agents/router.ts:10-15, src/mastra/agents/concierge.ts:98-105, src/tests/smoke.test.ts:50-65
Router Agent Architecture
The Router Agent (router-agent) is designed as a lean, non-conversational middleware. Its primary objective is to classify user intent and dispatch the appropriate background workflow. It is explicitly instructed never to write prose responses or search manually, leaving the user-facing UX entirely to the Concierge.
Intent Classification and Dispatch
The router follows a two-step logic for every request:
- Classify: Calls the
classify-intenttool to map the input to a specific category. - Dispatch: If confidence is ≥ 0.6, it triggers a workflow; otherwise, it asks a clarifying question.
The following diagram illustrates the routing logic:
The router preserves context by inheriting the previous intent if a follow-up depends on a prior topic (e.g., "is it walkable?" after a rental search).
Sources: src/mastra/agents/router.ts:7-45, src/mastra/workflows/concierge-routing-workflow.ts:145-200
Concierge Agent Logic
The Concierge Agent (concierge-agent) is the central intelligence for Medellín discovery. Unlike the Router, it maintains an extensive working memory to handle multi-turn conversations and manages a suite of specialized tools for restaurants, attractions, and grounded local searches.
Working Memory Schema
The agent utilizes a structured working memory to track state across a thread, defined by conciergeWorkingMemorySchema.
| Field | Type | Description |
|---|---|---|
lastIntent | Enum | Tracks the most recent intent (rental, event, restaurant, etc.) |
lastRentalQuery | Object | Stores filters like neighborhood, bedrooms, and budgetType |
lastRentalResults | Array | IDs and headlines of listings shown in the last reply |
selectedListingId | String | The specific listing currently focused for follow-ups |
mapUi | Object | Mirror of map state (viewport, pin counts, selected IDs) |
Sources: src/mastra/agents/concierge.ts:19-75, src/mastra/agents/tests/concierge.test.ts:25-50
Multi-Tool Orchestration
The Concierge selects between multiple search tools based on the specific type of query:
The Concierge is specifically instructed to use search-grounded-places for nightlife and cafés to leverage Google Maps grounding, while reserving search-restaurants for traditional dining.
Sources: src/mastra/agents/concierge.ts:107-140, src/mastra/agents/tests/concierge.test.ts:12-23
Pre-Search Clarification Gates
To ensure high-quality search results, the Concierge implements "Clarification Gates" for rentals and events. These gates prevent premature tool calls when critical information is missing.
Rental Search Gate
The agent scores the message based on hasBudget, hasBedrooms, and hasVibe. It will only call search-rentals immediately if confidence is ≥ 0.6. If confidence is lower, it sends exactly one grouped clarification message (e.g., "What dates, budget, and setup are you looking for?").
Event Discovery Gate
The agent checks for hasCategory, hasDateWindow, or hasNeighborhood. If the request is a generic city-only query (e.g., "events in Medellín"), it triggers a clarification message rather than searching.
Sources: src/mastra/agents/concierge.ts:153-205, src/mastra/workflows/concierge-routing-workflow.ts:55-115
Neighborhood & Budget Intelligence
The agents are programmed with Medellín-native intelligence to provide contextually relevant advice.
| Neighborhood | Characteristics |
|---|---|
| Laureles | Walkable, local vibe, remote-work friendly, calmer nightlife. |
| El Poblado | Upscale, high tourism, primary nightlife hub. |
| Envigado | Family-friendly, residential parques, quiet. |
| Belen | Budget-friendly, local feel, mid-city. |
Budget Processing Logic
When a user provides a budget, the Concierge categorizes it into budgetType:
- Nightly: If value < 200.
- Monthly: If 1000–4000 with keywords like "long-term" or "month".
- Total Trip: If explicitly stated; the agent then divides by trip length to derive a nightly rate.
Sources: src/mastra/agents/concierge.ts:141-152, src/mastra/workflows/concierge-routing-workflow.ts:35-50
Implementation Summary
Both agents are registered in the main Mastra instance within src/mastra/index.ts. They are tested for registration and model consistency (Gemini 3.5 Flash) in the project smoke tests.
// src/mastra/index.ts
export const mastra = new Mastra({
agents: {
pingAgent,
routerAgent,
rentalAgent,
conciergeAgent,
eventAgent,
evaluationAgent,
hostEventAgent,
},
workflows: {
rentalSearchWorkflow,
eventDiscoveryWorkflow,
conciergeRoutingWorkflow,
},
// ... configuration
});
Sources: src/mastra/index.ts:25-45, src/tests/smoke.test.ts:15-30
The Core Mastra Agents provide a robust routing and interaction layer that combines deterministic logic (Router) with high-context generative capabilities (Concierge) to facilitate discovery in the Medellín ecosystem.