🤖 Agentic Todo Sample

An AI-powered todo management system built with Arcade.dev, featuring natural language interaction with todo lists and Gmail integration.

✨ Features

🧠 Multi-Agent Architecture

• Conversation Agent: Main supervisor that routes requests to specialized agents
• Todo Agent: Manages todo tasks with natural language commands
• Google Agent: Handles Gmail and Google account operations

📝 Todo Management

• Natural Language Interface: Create, view, and manage tasks using conversational AI
• Smart Task Operations:
  • Add tasks with descriptions and dates
  • Mark tasks as completed
  • Filter pending tasks
  • Query tasks by date ranges
  • Get all pending tasks instantly

📧 Gmail Integration

• List and manage emails through natural language
• Seamlessly switch between todo and email contexts
• Unified conversation interface for both services

🔄 Persistent Memory

• PostgreSQL database backend for reliable task storage
• Conversation state management with LangGraph checkpointing
• Thread-based conversation continuity

🛠️ Developer-Friendly

• Comprehensive test suite with pytest
• Evaluation framework for tool performance
• Clean modular architecture
• Full type hints and documentation

🚀 Quick Start

Prerequisites

• Python 3.13+
• PostgreSQL database (Supabase recommended)
• OpenAI API key
• Arcade.ai API key

🔧 Local Development Setup

1. Clone the repository

   git clone <repository-url>
   cd agentic-todo-sample

2. Install dependencies using uv

   # Install uv if you haven't already
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install project dependencies
   uv sync

3. Set up environment variables

   # Create .env file in the root directory
   echo "ARCADE_API_KEY=your_arcade_api_key_here" >> .env
   echo "OPENAI_API_KEY=your_openai_api_key_here" >> .env
   echo "SUPABASE_URL=your_database_connection_string" >> .env

4. Set up Supabase database

   # Create a new Supabase project at https://supabase.com
   # Get your database URL from Project Settings > Database
   
   # Navigate to todo_memory directory
   cd todo_memory
   
   # Create the database schema using the provided SQL
   # Replace YOUR_DATABASE_URL with your actual Supabase connection string
   psql -d YOUR_DATABASE_URL -f create.sql
   
   # Alternative: Use Supabase SQL Editor
   # Copy the contents of create.sql and run it in your Supabase SQL Editor

5. Deploy the worker

   # Deploy the todo memory worker to Arcade
   arcade deploy

   (see Deploy to Arcade.dev for details on how to configure the Arcade worker)

6. Run the agent locally

   # From the root directory
   python main.py

7. Start chatting!

   User: Add a task to buy groceries tomorrow
   User: Show me all my pending tasks
   User: Mark task 1 as done
   User: Check my recent emails
   

☁️ Deploy to Arcade.dev

1. Prepare Your Toolkit

First, build and deploy the todo memory toolkit:

cd todo_memory
make build

2. Configure Worker Settings

The worker.toml file is already configured:

[[worker]]

[worker.config]
id = "mini-todo-worker"
enabled = true
timeout = 30
retries = 3
secret = "7d80b78c8e20f751aa06f708c5680a63"

[worker.local_source]
packages = ["./todo_memory"]

3. Deploy with Arcade CLI

# Install Arcade CLI
pip install arcade-ai[all]

# Login to Arcade
arcade login

# Deploy your worker
arcade deploy

4. Set Environment Variables

In your Arcade.dev dashboard:

1. Navigate to your worker settings
2. Add environment variables:
   • SUPABASE_URL: Your Supabase connection string

5. Test Your Deployed Agent

Your agent will be available at your Arcade.dev endpoint. Test it with some of these prompts:

Read my latest emails, decide which ones are important, and add a task to reply to each of the important ones

Add a task to prepare for the team meeting next Friday with details about reviewing the Q1 budget

Show me all my pending tasks and then check if I have any important emails from my manager

I just finished my presentation - mark that task as done and add a new task to follow up with the client by tomorrow

What tasks did I create since the beginning of this month? Also, do I have any emails about the project deadline?

Create a task for this weekend to clean my apartment, then tell me about any emails I received in the last few days

Available Tools

Todo Memory Tools

• TodoMemory_GetTasks: Get tasks with optional filtering
• TodoMemory_GetAllPendingTasks: Get all pending tasks
• TodoMemory_AddTask: Create new tasks
• TodoMemory_MarkTaskAsDone: Complete tasks

Google Tools

• Google_ListEmails: List and search emails

🔧 Configuration

Database Schema

The todo database uses a simple but effective schema:

CREATE TABLE tasks (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    description TEXT,
    date DATE DEFAULT CURRENT_DATE,
    pending BOOLEAN DEFAULT TRUE
);

📚 Learn More

• Arcade.dev Documentation
• LangGraph Documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.