Agent Actions & Tool Library
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Actions & Tool Library forms the core functional layer of the mdeapp discovery platform. It enables AI agents to interact with real-world data sources, including Supabase databases for rentals and events, Google Maps for grounded POI discovery, and live web searches for time-sensitive verification. This system follows a strictly governed execution model where tool outputs are considered the "only truth," preventing the AI from hallucinating details about venues, prices, or availability.
Sources: src/mastra/agents/concierge.ts:257-258, README.md:1-15
Core Discovery Tools
The platform utilizes specialized tools to handle different discovery verticals. These tools are primarily registered within the conciergeAgent and eventAgent to provide localized intelligence for Medellín.
Discovery Tool Categorization
| Tool ID | Primary Purpose | Key Parameters |
|---|---|---|
search-rentals | Discovery of apartments and stays. | queryText, maxPricePerNight, minBedrooms |
search-events | Finding ticketed concerts, festivals, and sports. | category, dateWindow, neighborhood |
search-grounded-places | POI discovery (cafés, bars, salsa venues) via Google Maps. | queryText, intent (nightlife/cafe), locationBias |
search-restaurants | Sit-down meal discovery (lunch, dinner, brunch). | queryText |
search-web-grounded-events | Live web verification for time-sensitive facts. | query, sqlEventCount |
Sources: src/mastra/agents/concierge.ts:79-106, src/mastra/tools/search-web-grounded-events.ts:15-30
Execution Logic & Intent Routing
The routerAgent acts as the primary orchestrator, classifying user intent before dispatching to specific workflows or agents. It utilizes the classifyIntentTool to ensure high-confidence mapping to verticals like rental_search or event_discovery.
The diagram shows the intent classification and dispatch flow used by the router to manage tool execution.
Sources: src/mastra/agents/router.ts:10-38
Grounding & Verification Systems
To ensure technical accuracy, the system employs multiple layers of grounding.
Search Web Grounded Events
This tool is used as a fallback or verification layer. It is triggered only when standard database searches (search-events) return fewer than 3 results or when a user specifically asks for live verification (e.g., "verify ticket links"). It invokes an internal ADK grounding client to fetch fresh web data.
Sources: src/mastra/tools/search-web-grounded-events.ts:16-55, src/mastra/agents/concierge.ts:192-198
POI Grounding (Google Maps)
The search-grounded-places tool is strictly separated from restaurant searches. It is specifically used for "vibe-heavy" discovery such as salsa bars, hidden rooftops, or laptop-friendly cafés. It supports locationBias derived from the frontend map's viewport.
Sources: src/mastra/agents/concierge.ts:85-98
Telemetry and Audit Framework
The project implements a production-safe AI tracing system (AGT-00C) that records tool-timing spans and token usage without requiring external observability packages.
Tool Span Recording
Every tool execution is recorded as a ToolSpan on a shared RequestContext. This data is eventually persisted in the ai_runs table within Supabase.
| Field | Description |
|---|---|
tool | The ID of the tool called (e.g., search-rentals). |
ms | Wall-clock duration of the call. |
status | Execution status: ok or error. |
ts | Epoch timestamp of call start. |
Sources: src/mastra/lib/tool-audit-context.ts:28-40, src/mastra/lib/mastra-telemetry.ts:7-20
Telemetry Data Flow
The sequence shows how tool metrics are collected in-memory during a request and then flushed to the database as telemetry metadata.
Sources: src/mastra/lib/tool-audit-context.ts:50-100, src/mastra/lib/mastra-telemetry.ts:55-75
Trusted Data Sources
The library maintains a registry of trusted Medellín event sources. These are categorized by tiers (official, ticketing, nightlife, etc.) and locales.
- Official Tiers: Medellín Travel, Plaza Mayor, INDER Medellín.
- Ticketing Tiers: Eventbrite, TuBoleta, La Tiquetera.
- Nightlife Tiers: Resident Advisor, Songkick, Bandsintown.
Sources: src/lib/events/trusted-event-sources.ts:28-52
Operational Invariants
- Hallucination Prevention: Agents must never invent event names, venues, or prices. If a tool returns zero results, the agent must state this and suggest relaxing filters.
- Output Formatting: Agents are forbidden from listing venue names in prose if the UI is already rendering photo cards (e.g., after
search-grounded-places). - Maximum Results: Tools and agent replies are capped at a maximum of 5 cards per response to maintain UI performance and clarity.
Sources: src/mastra/agents/concierge.ts:257-264, src/mastra/agents/event-agent.ts:100-105
This tool library ensures that agent actions are deterministic, auditable, and grounded in verifiable data sources, providing a reliable discovery experience for the Medellín ecosystem.