Ascilla - The web Butler

A multi-agent system for completing real-world tasks using Google Gemini 2.5 Flash.

Features

• Medicine Finder: Find nearby pharmacies and simulate calls to check stock
• Bali Itinerary Planner: Create personalized travel itineraries with iterative updates
• Generative UI: Dynamic component rendering based on task context
• Task Registry: Easily extensible architecture for adding new tasks

Setup

Backend

cd server
npm install
cp .env.example .env
###add your GEMINI_API_KEY to .env
npm run dev

Frontend

cd client
npm install
npm run dev

Usage

1. Start the backend server (port 5000)
2. Start the frontend dev server (port 3000)
3. Open http://localhost:3000
4. Try:
   • "Find me ibuprofen 200mg near downtown"
   • "Plan a 5-day Bali trip with $2000 budget"
   • "Change day 2" (after creating an itinerary)

Architecture

• Orchestrator: Manages task flow and agent coordination
• Planner Agent: Breaks down user intent into steps
• Retrieval Agent: Simulates data fetching
• Executor Agent: Generates outcomes
• UI Agent: Determines which components to render

1. High-Level Multi-Agent Architecture

   graph TD
    User((User)) -- Natural Language --> Orchestrator{Orchestrator}
    
    subgraph "Agentic Core"
        Orchestrator -- Task/Intent --> Planner[Planner Agent]
        Planner -- Sub-tasks --> State[(Global State)]
        
        State -- Requirements --> Discovery[Retrieval Agent]
        State -- Actions --> Executor[Executor Agent]
        
        Discovery -- Data/API Results --> State
        Executor -- Sim-Call Transcripts --> State
    end
    
    State -- Current Context --> UIGen[Generative UI Engine]
    UIGen -- Dynamic Components --> User
    
    %% Styling
    style Orchestrator fill:#3b82f6,stroke:#fff,color:#fff
    style Planner fill:#10b981,stroke:#fff,color:#fff
    style Executor fill:#ef4444,stroke:#fff,color:#fff
    style State fill:#f59e0b,stroke:#fff,color:#fff

2. Task 1: Medicine Verification Loop

   sequenceDiagram
    participant U as User
    participant O as Orchestrator
    participant R as Retrieval Agent
    participant E as Executor (Sim)
    participant UI as Generative UI

    U->>O: "Find Paracetamol near me"
    O->>UI: Render Dosage Selector
    UI->>U: "Which dosage? 500mg/1000mg"
    U->>O: Selects 500mg
    O->>R: Query Google Maps (Pharmacy + Open Now)
    R-->>O: List of 3 nearby stores
    O->>E: Initiate Verification Call (Store #1)
    Note over E: Simulating Call to Store...
    E-->>UI: Stream Live Transcript
    E-->>O: Confirmation: Stock Available
    O->>UI: Render Success Card + Reservation Button

3. Task 2: Iterative Travel Planning

   flowchart LR
    A[User Intent] --> B{Preferences Extracted?}
    B -- No --> C[UI: Ask Dates/Budget/Interests]
    C --> A
    B -- Yes --> D[Planner: Generate Macro-Plan]
    D --> E[Render Itinerary Overview]
    E --> F{User Feedback?}
    F -- "Change Day 2" --> G[Planner: Selective Re-generation]
    G --> E
    F -- "Looks Good" --> H[Final Artifact: Actionable Itinerary]
    H --> I[Execute Bookings/Reservations]

4. Scalability: The Plugin Model (Future Development)

   graph TD
    Core[Core Orchestrator] --> Interface[Task Interface]
    
    subgraph Plugins
        Interface --> Medicine[Medicine Module]
        Interface --> Travel[Travel Module]
        Interface --> Services[Service Module: Plumber/Electrician]
    end
    
    subgraph SharedTools[Shared Tool Library]
        Medicine --> Search[Neural Search Tool]
        Travel --> Search
        Services --> Search
        
        Medicine --> Call[Sim-Call/SMS Tool]
        Services --> Call
    end