• 

• 

• 

🛠️ Google Technologies Compliance Matrix (Mandatory Criteria)

This project strictly satisfies all three required Google technology tiers:

1. Model Layer (Gemini 3.5+):

   • Technology: Gemini 3.6 Flash accessed directly via the official Gemini API / Vertex AI endpoints.
   • Usage: Powers the core autonomous reasoning engine, schema validation, and JSON sorting plan generation.

2. Google Agent Framework:

   • Technology: Google ADK (Agent Development Kit) 2.6 (and Google GenAI SDK).
   • Usage: Orchestrates agent lifecycle, human-in-the-loop task runners, and MCP toolset execution (ADK McpToolset).

3. Google Cloud Infrastructure Service:

   • Technology: Google Cloud Firestore.
   • Usage: Serves as the cloud-native state store and transaction log for the Global Undo Architecture, persisting real-time file-move payloads with atomic transaction security.

---

The Problem

Every enterprise has the same problem: chaotic downloads folders, messy project workspaces, and data silos overflowing with unstructured files. Manual organization is tedious, error-prone, and never scales. But simply handing the keys to a generative AI agent to move and delete local files is a massive security risk. We needed a way to bridge the gap between autonomous execution and enterprise-grade safety.

What it does

The Kaggle Concierge Agent is a production-quality CLI agent that autonomously organizes your messy workspaces using natural language. It doesn't just execute blindly; it operates on a strict SCAN, PLAN, CONFIRM human-in-the-loop boundary.

1. Scans your workspace root using a live MCP (Model Context Protocol) filesystem server.
2. Proposes a clean, human-readable JSON sorting plan with category assignments.
3. Waits for explicit Y/N terminal approval before a single file is touched.
4. Executes the approved plan, moving files into categorized subfolders.

To make this truly enterprise-ready, we engineered two critical AgentOps guardrails:

Global Undo Architecture: Every file move is logged sequentially to a Google Cloud Firestore transaction log (with a local .json fallback), allowing for instant, deterministic reversions if a mistake is made.

Graceful Degradation: If the Gemini API returns a 429 quota error or 500 server timeout, the agent doesn't crash. It silently falls back to a zero-downtime offline heuristic engine to finish the job safely.

How we built it

We architected the agent natively on Google ADK 2.6 to ensure seamless orchestration.

The Brain: The core reasoning engine is powered by Gemini 3.6 Flash, chosen for its rapid JSON-mode structuring capabilities and massive context window.

The Hands: We bypassed fragile custom scripts by directly integrating the standard modelcontextprotocol/server-filesystem via npx and connecting it to the ADK McpToolset.

The Safety Net: The terminal interface and asynchronous task runner (asyncio) were engineered in Python to handle the human-in-the-loop interruptions and API fallback state management.

Challenges we ran into

Our biggest hurdle was handling I/O and asynchronous pipe closures on Windows during the MCP server shutdown. The raw asyncio loop would often throw messy fatal transport errors when exiting. We solved this by implementing custom exception suppression (loop.set_exception_handler) to ensure the CLI exits with a clean code 0, preserving the UX.

Furthermore, designing a deterministic Undo for a non-deterministic LLM required entirely separating the execution state from the LLM context. By piping the execution payload directly into Firestore before the OS moves the file, we guaranteed a secure paper trail.

Accomplishments that we're proud of

We are incredibly proud of the Offline Expert Mode. Proving that an agentic workflow can survive a total cloud API failure and continue executing via local fallbacks is a massive step forward for trusting AI in critical infrastructure.

What we learned

We learned the sheer power of the Model Context Protocol (MCP). By treating the filesystem as a standardized external tool rather than writing bespoke Python OS wrappers, the Gemini agent was able to natively understand its operational boundaries with far less prompt engineering.

What's next for Kaggle Concierge Agent

We plan to expand the MCP toolkit. The next step is integrating a Google Drive MCP server so the agent can autonomously sync, back up, and organize cloud files alongside local directories, effectively becoming a hybrid-cloud data concierge.

Demo Walkthrough (See Video)

00:10: The agent receives the organize command and instantly initializes the Model Context Protocol (MCP) server.

00:16: Gemini 3.6 Flash analyzes the workspace and outputs a highly structured JSON execution plan.

00:29: Human-in-the-Loop Checkpoint. The system halts and explicitly requires Y/N approval before a single file is touched.

00:30: Execution and real-time directory reorganization.

03:58 to 04:06 (Code Review): Demonstration of our Global Undo Architecture (Firestore transaction logging) and the resilient offline heuristic fallback logic.

Built With

• agentops
• gemini-3.6-flash
• google-adk
• google-cloud-firestore
• model-context-protocol
• python