doc/AGENTS.md

🤖 The Agent Team

LifeFlow AI is not a single bot, but a coordinated Multi-Agent System (MAS). Each agent is a specialized "worker" with restricted permissions, specific tools, and a distinct model configuration to optimize for cost and performance.

👥 The Roster

1. 📋 Planner (The Architect)

• Model: Gemini 2.5 Flash (High Reasoning)
• Role: The entry point. It never executes tasks but "understands" them.
• Responsibility:
  • Parses vague natural language into structured JSON.
  • Assigns categories (MEAL, SIGHTSEEING) and priorities.
  • Estimates durations based on context (e.g., "coffee" = 30m, "museum" = 2h).

2. 👨‍✈️ Team Leader (The Orchestrator)

• Model: Gemini 2.5 Flash
• Role: The State Machine. It manages the core_team.
• Responsibility:
  • Receives the Task List from the Planner.
  • Enforces the strict pipeline sequence: Scout -> Optimizer -> Navigator.
  • Handles error recovery (e.g., if Scout fails, it asks to retry).
  • Crucial: It does not see the raw data, only the Reference IDs.

3. 🗺️ Scout (The Explorer)

• Model: Gemini 2.5 Flash-Lite (Speed Optimized)
• Tools: ScoutToolkit (Google Places API)
• Key Feature: Robust JSON Parsing. The Scout includes a custom parser to handle malformed JSON often output by LLMs, ensuring high reliability even with smaller models.
• Task: Performs "Adaptive Search" (allocating more API budget to harder queries).

4. ⚡ Optimizer (The Mathematician)

• Model: Gemini 2.5 Flash-Lite
• Tools: OptimizationToolkit (Google OR-Tools)
• Algorithm: TSPTW (Traveling Salesperson Problem with Time Windows).
• Logic:
  • Loads POIs from the DB.
  • Calculates a Distance Matrix (Manhattan/Haversine approximation).
  • Reorders stops to minimize travel time while respecting opening hours.
  • Marks tasks as "Dropped" if they don't fit the schedule.

5. 🧭 Navigator (The Driver)

• Model: Gemini 2.5 Flash-Lite
• Tools: NavigationToolkit (Google Routes API)
• Task:
  • Takes the logical sequence from the Optimizer.
  • Queries Google Routes API for precise "Traffic-Aware" travel times.
  • Generates the polyline geometry for the map UI.

6. 🌤️ Weatherman (The Meteorologist)

• Model: Gemini 2.5 Flash-Lite
• Tools: WeatherToolkit (OpenWeatherMap)
• Innovation: Dynamic Timezone Handling.
  • Calculates the exact arrival time at each stop.
  • Fetches the specific forecast for that hour and location.
  • Retrieves Air Quality Index (AQI).

---

🧠 Model Configuration Strategy

We use a tiered model strategy to balance intelligence and latency:

Agent Tier	Model	Rationale
Brain Tier (Planner, Leader)	gemini-2.5-flash	Requires complex instruction following and context management. Needs higher context window.
Muscle Tier (Scout, Optimizer, etc.)	gemini-2.5-flash-lite	Performs single-shot tool execution. Speed is prioritized over nuance.

🛡️ Tool Isolation (Exclusive Mode)

In app.py, we implement a unique Exclusive MCP Connection:

# Pseudo-code logic from app.py
AGENT_TOOL_MAP = {
    "scout": "search_and_offload",
    "optimizer": "optimize_from_ref",
    # ...
}

# Each agent gets its own private server instance
for agent, tool in AGENT_TOOL_MAP.items():
    connect_mcp(agent, include_tools=[tool])
This prevents the "Navigator" from accidentally trying to search for places, or the "Scout" from trying to calculate routes, significantly reducing loop errors.