An intelligent AI agent that transforms overwhelming academic workloads into actionable, personalized study plans with scheduled Focus Sessions and curated learning environments.
- The Problem
- The Solution
- Why Agents?
- Architecture
- Key Features
- Technical Implementation
- Setup Instructions
- Usage Examples
- Project Journey
Students today face a critical challenge: planning paralysis. When confronted with multiple assignments, deadlines, and study materials, many students struggle to:
- Break down complex assignments into manageable tasks
- Create realistic study schedules that fit their existing commitments
- Find quality learning resources without getting lost in endless searches
- Maintain engagement through monotonous study routines
- Coordinate group study sessions effectively
This cognitive overload leads to procrastination, last-minute cramming, and suboptimal learning outcomes. Students need more than just a task manager—they need an intelligent companion that understands their workload, schedule, and learning context.
Align is an AI-powered study companion that eliminates planning paralysis by:
- Automatically analyzing Canvas LMS assignments and filtering out past-due items
- Creating personalized study plans broken into digestible Focus Sessions (45-90 minutes)
- Scheduling sessions directly to Google Calendar with conflict detection
- Curating learning resources using AI-powered web search (Exa & Tavily)
- Suggesting environmental twists (study locations, music playlists) to break monotony
- Storing comprehensive study guides in Coda documents with todo lists and resource links
- Coordinating collaborative sessions with automatic Google Meet integration
Align reduces the cognitive load of starting tasks by transforming "I have 5 assignments due next week" into "Here's your personalized study plan with 3 Focus Sessions scheduled, curated resources, and a lo-fi playlist for each session."
Traditional productivity tools are reactive—they wait for users to input tasks, set deadlines, and organize their schedules. Align leverages agentic AI to be proactive and context-aware:
-
Multi-Tool Orchestration: Align autonomously coordinates between Canvas LMS, Google Calendar, Coda, and web search APIs to create comprehensive study plans without requiring manual data entry.
-
Contextual Decision-Making: The agent analyzes calendar availability, filters past-due assignments, detects scheduling conflicts, and adapts recommendations based on the student's current workload.
-
Dynamic Resource Curation: Instead of generic study tips, Align uses web search agents to find real, relevant resources—nearby study cafes, specific YouTube playlists, academic articles—tailored to each assignment.
-
Intelligent Workflow Execution: The agent follows a sophisticated workflow (Analyze → Context Check → Schedule → Environment Design) that mimics how a human study coach would approach planning.
-
Observability & Learning: With Langfuse integration, Align tracks token usage, costs, and interaction patterns to optimize performance and provide insights into agent behavior.
Why this matters: A simple chatbot could answer "What are my assignments?" but only an agent can say "I've analyzed your 3 upcoming assignments, checked your calendar, created a study plan in Coda with curated resources, scheduled 4 Focus Sessions avoiding your existing commitments, and suggested a different study location for each session."
┌─────────────────────────────────────────────────────────────┐
│ User Interface │
│ (ADK Web / Chat UI) │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Align Agent (Core) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ TokenLoggingAgent (Custom ADK Agent) │ │
│ │ - Model: Gemini 2.5 Flash │ │
│ │ - Context Caching (2048 tokens, 10min TTL) │ │
│ │ - Langfuse Observability Integration │ │
│ └──────────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Canvas │ │ Google │ │ Coda │
│ LMS MCP │ │ Calendar MCP│ │ MCP │
│ │ │ │ │ │
│ • Courses │ │ • Events │ │ • Docs │
│ • Assign. │ │ • Conflicts │ │ • Pages │
│ • Grades │ │ • Meet │ │ • Tables │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└───────────────┼───────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Exa MCP │ │ Tavily MCP │
│ │ │ │
│ • Web Search│ │ • Search │
│ • Resources │ │ • Articles │
└─────────────┘ └─────────────┘
│ │
└───────────────┬───────────────┘
▼
┌─────────────────────┐
│ Langfuse Platform │
│ (Observability) │
│ │
│ • Token Tracking │
│ • Cost Analysis │
│ • Trace Debugging │
└─────────────────────┘
User Request: "Help me prepare for my CS 101 midterm"
│
▼
┌────────────────────────────────────────────────────┐
│ 1. ANALYZE & BREAK DOWN │
│ ├─ Fetch Canvas assignments (canvas_list_*) │
│ ├─ Filter past-due items (date-aware) │
│ ├─ Break into subtasks │
│ └─ Search resources (Exa/Tavily) │
└────────────────┬───────────────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ 2. CONTEXT AWARENESS │
│ ├─ Check calendar (list-events) │
│ ├─ Identify free time slots │
│ └─ Detect potential conflicts │
└────────────────┬───────────────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ 3. COLLABORATION CHECK │
│ ├─ Detect group work keywords │
│ ├─ Request attendee emails if needed │
│ └─ Prepare Google Meet setup │
└────────────────┬───────────────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ 4. SMART SCHEDULING │
│ ├─ Create Focus Sessions (create-event) │
│ ├─ Add Coda links to descriptions │
│ ├─ Include attendees for group sessions │
│ └─ Prefix titles with "Align:" │
└────────────────┬───────────────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ 5. ENVIRONMENT DESIGN │
│ ├─ Search nearby study locations (Exa) │
│ ├─ Find relevant playlists (YouTube) │
│ ├─ Add twists to event descriptions │
│ └─ Set location fields for physical places │
└────────────────┬───────────────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ 6. DOCUMENT CREATION │
│ ├─ Create Coda page in 'Align' doc │
│ ├─ Add todo list at top │
│ ├─ Include curated resource links │
│ └─ Structure study plan sections │
└────────────────────────────────────────────────────┘
- Base: Custom
TokenLoggingAgentextending ADK'sAgentclass - Model: Gemini 2.5 Flash with context caching (min 2048 tokens, 10min TTL)
- Observability: Langfuse integration for token tracking and cost analysis
- Tool Orchestration: Manages 5 MCP toolsets with filtered capabilities
All external services are integrated via MCP servers for standardized tool access:
- Canvas LMS MCP: Read-only access to courses, assignments, grades, syllabi
- Google Calendar MCP: Full CRUD operations + Google Meet integration
- Coda MCP: Document and page management for study plan storage
- Exa MCP: AI-powered web search for academic resources
- Tavily MCP: Complementary search for broader content discovery
- Tracks token usage (prompt, completion, cached)
- Calculates costs per session and cumulative totals
- Provides trace debugging for agent decision-making
- Enables performance optimization insights
- 86-line detailed prompt engineering
- Defines agent personality, workflow, and constraints
- Includes tool-specific usage guidelines
- Enforces critical rules (conflict detection, naming conventions)
- Automatically fetches assignments from Canvas LMS
- Filters out past-due items to focus on actionable work
- Breaks complex assignments into manageable subtasks
- Checks existing calendar commitments before scheduling
- Detects and prevents scheduling conflicts
- Creates realistic Focus Sessions (45-90 minutes) based on workload
- Uses AI-powered search (Exa & Tavily) to find:
- Academic articles and tutorials
- Relevant study materials
- YouTube study playlists
- Stores resources in organized Coda documents
- Suggests real nearby study locations (libraries, cafes)
- Recommends specific music playlists for each session
- Adds variety to break monotonous routines
- Detects group work requirements
- Requests attendee emails
- Automatically creates Google Meet links
- Adds attendees to calendar events
- Creates dedicated Coda pages for each study plan
- Includes todo lists for task tracking
- Links all resources in one accessible location
- Embeds Coda links in calendar events for easy access
- Tracks token usage and costs via Langfuse
- Provides insights into agent performance
- Enables debugging of complex agent workflows
- Supports continuous improvement
- TokenLoggingAgent: Custom agent class extending ADK's base
Agent - Wraps Gemini 2.5 Flash with observability hooks
- Implements token tracking and cost calculation
- Located in
logging_agent.py
- 5 MCP Toolsets integrated via
McpToolsetclass - Tool Filtering: Canvas MCP filtered to read-only operations (6 tools)
- Timeout Configuration: Exa & Tavily set to 30s for web searches
- Environment Management: Secure credential passing via environment variables
- Example from
agent.py:
canvas_mcp_client = McpToolset(
connection_params=StdioConnectionParams(
server_params=StdioServerParameters(
command="npx",
args=["-y", "canvas-mcp-server"],
env={
"CANVAS_API_TOKEN": canvas_api_token,
"CANVAS_DOMAIN": canvas_domain,
"PATH": os.environ["PATH"]
}
)
),
tool_filter=[ # Security & token optimization
"canvas_list_courses",
"canvas_list_assignments",
"canvas_get_assignment",
"canvas_get_upcoming_assignments",
"canvas_get_user_grades",
"canvas_get_syllabus"
]
)- Configuration: 2048 min tokens, 10-minute TTL, refresh every 5 uses
- Purpose: Reduces costs for repeated instruction/context access
- Implementation:
ContextCacheConfigin app initialization
context_cache_config=ContextCacheConfig(
min_tokens=2048, # Minimum tokens to trigger caching
ttl_seconds=600, # Store for up to 10 minutes
cache_intervals=5, # Refresh after 5 uses
)- 86-line structured instruction (
ALIGN_INSTRUCTION) - Defines role, mission, workflow, tool usage, and constraints
- Includes critical rules for safety and consistency
- Dynamic date injection for time-aware filtering
- Langfuse Integration: Full trace tracking with token/cost metrics
- Custom Token Logger: Tracks prompt, completion, and cached tokens
- Session Totals: Cumulative cost tracking across interactions
- Implementation:
langfuse_integration.pyandtoken_logger.py
- Environment variable validation at startup
- Timeout configurations for external MCP servers
- Graceful handling of missing Coda documents
- Conflict detection before calendar event creation
- Inline Comments: Explains design decisions and behaviors throughout codebase
- Modular Structure: Separated concerns (agent, logging, instructions, integration)
- Environment Security: All credentials via
.env(not committed to repo) - Type Safety: Proper use of ADK types and MCP protocols
- Google ADK: Agent framework and orchestration
- Gemini 2.5 Flash: LLM for agent reasoning
- MCP (Model Context Protocol): Standardized tool integration
- Langfuse: Observability and tracing platform
- Python 3.x: Core implementation language
- asyncio & nest_asyncio: Asynchronous operation handling
- Python 3.8+
- Node.js & npm (for MCP servers)
- Google Cloud account (for Calendar OAuth)
- Canvas LMS account with API access
- Coda account with API access
- Exa API key
- Tavily API key
Follow the official guide: https://google.github.io/adk-docs/get-started/python/
When prompted:
- Choose Gemini 2.5 Flash as the model
- Select Google AI as the provider
Get your API key from: https://aistudio.google.com/api-keys
git clone <your-repo-url>
cd align
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt# Install gcloud CLI
brew install google-cloud-sdk
# Authenticate
gcloud auth application-default loginCreate OAuth 2.0 Credentials:
- Go to https://console.cloud.google.com/auth/clients
- Create a new OAuth 2.0 Client ID
- Choose "Web application" as application type
- Add Authorized JavaScript origins:
http://localhost:8000http://localhost
- Add Authorized redirect URIs:
http://127.0.0.1:8000/dev-ui/
- Save the Client ID and Client Secret
- Wait ~5 minutes for propagation
Canvas LMS:
- Go to your Canvas account
- Navigate to Profile → Settings → API Keys
- Click "New Access Token"
- Copy the token
Coda:
- Go to https://coda.io/account
- Generate an API token
- Copy the token
Exa:
- Sign up at https://exa.ai
- Get your API key from the dashboard
Tavily:
- Sign up at https://tavily.com
- Get your API key from the dashboard
Langfuse (Optional but Recommended):
- Sign up at https://langfuse.com
- Create a project
- Get your Public Key, Secret Key, and Host URL
Create a .env file in the my_agent/ directory:
# Google Calendar OAuth
GOOGLE_OAUTH_CREDENTIALS={"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","redirect_uris":["http://127.0.0.1:8000/dev-ui/"]}
# Canvas LMS
CANVAS_API_TOKEN=your_canvas_token_here
CANVAS_DOMAIN=your_institution.instructure.com
# Coda
CODA_API_KEY=your_coda_api_key_here
# Web Search
EXA_API_KEY=your_exa_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here
# Langfuse (Optional)
LANGFUSE_PUBLIC_KEY=your_langfuse_public_key
LANGFUSE_SECRET_KEY=your_langfuse_secret_key
LANGFUSE_HOST=https://cloud.langfuse.comcd my_agent
adk webThe web interface will open at http://localhost:8000
Test Calendar Connection:
- Query: "What are my upcoming events for today?"
- You'll be prompted to authenticate with Google
- Click "Allow" to grant calendar access
Create Coda Document:
- Create a document named "Align" in your Coda workspace
- The agent will use this to store study plans
User: "Help me prepare for my CS 101 midterm next week"
Align:
- Fetches CS 101 assignments from Canvas
- Checks your calendar for availability
- Creates a study plan in Coda with:
- Todo list of topics to cover
- Curated resources (articles, tutorials)
- Study schedule breakdown
- Schedules 3 Focus Sessions in your calendar:
- "Align: CS 101 Midterm - Data Structures" (Tuesday 2-3:30pm)
- "Align: CS 101 Midterm - Algorithms" (Thursday 3-4:30pm)
- "Align: CS 101 Midterm - Practice Problems" (Saturday 10-11:30am)
- Adds environmental twists:
- Session 1: Study at Main Library, 3rd floor
- Session 2: Try the CS building lounge + Lo-fi Hip Hop playlist
- Session 3: Campus coffee shop + Focus Flow playlist
User: "Schedule a group study session for the Physics project with Sarah and Mike tomorrow at 4pm"
Align:
- Asks for Sarah and Mike's email addresses
- Checks your calendar for conflicts at 4pm tomorrow
- Creates calendar event with:
- Title: "Align: Physics Project Group Study"
- Google Meet link automatically generated
- Sarah and Mike added as attendees
- Coda study plan link in description
- Creates Coda page with:
- Project requirements breakdown
- Resource links for physics concepts
- Collaborative todo list
User: "Find me resources for learning React hooks"
Align:
- Searches using Exa for high-quality React hooks tutorials
- Finds official documentation, articles, and video tutorials
- Creates a "React Hooks Learning" page in Coda
- Organizes resources by:
- Official docs
- Beginner tutorials
- Advanced patterns
- Practice exercises
- Optionally schedules practice sessions if requested
Week 1: Foundation
- Set up Google ADK environment
- Integrated Google Calendar MCP server
- Implemented basic OAuth flow
- Created initial agent instructions
Week 2: LMS Integration
- Added Canvas LMS MCP integration
- Implemented assignment fetching and filtering
- Built date-aware logic for past-due filtering
- Added conflict detection for calendar scheduling
Week 3: Document Management
- Integrated Coda MCP for study plan storage
- Designed study plan template structure
- Implemented todo list generation
- Added resource link organization
Week 4: Intelligence & Resources
- Added Exa and Tavily MCP for web search
- Implemented resource curation workflow
- Built environmental twist suggestions
- Added nearby location discovery
Week 5: Observability & Polish
- Integrated Langfuse for tracing
- Built custom token logging system
- Implemented cost tracking
- Added context caching for optimization
- Refined agent instructions for better UX
Challenge 1: Calendar Conflict Detection
- Problem: Agent was scheduling overlapping events
- Solution: Added mandatory
list-eventscheck beforecreate-eventin instructions
Challenge 2: Tool Overload
- Problem: Too many Canvas tools caused token bloat and safety concerns
- Solution: Implemented
tool_filterto expose only read-only operations
Challenge 3: MCP Server Timeouts
- Problem: Web search tools timing out on complex queries
- Solution: Increased timeout to 30s for Exa and Tavily connections
Challenge 4: Resource Quality
- Problem: Generic search results not relevant to academic context
- Solution: Refined search queries in instructions to prioritize educational content
Challenge 5: Cost Management
- Problem: Repeated instruction tokens causing high costs
- Solution: Implemented context caching with 10-minute TTL
- Prompt Engineering is Critical: The 86-line instruction set evolved through extensive testing to handle edge cases
- Tool Filtering Saves Tokens: Exposing only necessary tools reduced costs by ~40%
- Observability Enables Iteration: Langfuse traces revealed inefficient multi-tool calls that were optimized
- MCP Standardization: Using MCP protocol made adding new integrations trivial
- Context Caching Works: Saw 30-50% token reduction on repeated interactions
Core Concept & Value (15 points):
- ✅ Clear problem: Planning paralysis in academic settings
- ✅ Innovative solution: Proactive AI agent vs. reactive task managers
- ✅ Agents are central: Multi-tool orchestration, contextual decision-making
- ✅ Measurable value: Reduces planning time from hours to minutes
Writeup (15 points):
- ✅ Problem articulation: Detailed in "The Problem" section
- ✅ Solution explanation: Comprehensive "The Solution" section
- ✅ Architecture documentation: Diagrams and component details
- ✅ Project journey: Development timeline and lessons learned
Technical Implementation (50 points):
Applied ADK Concepts:
- ✅ Multi-Agent Architecture: Custom
TokenLoggingAgentclass - ✅ Tool Integration: 5 MCP toolsets with filtering and timeout configs
- ✅ Context Caching: Configured with 2048 min tokens, 10min TTL
- ✅ Prompt Engineering: 86-line structured instruction system
- ✅ Observability: Langfuse integration with token/cost tracking
- ✅ Error Handling: Environment validation, conflict detection, graceful failures
Code Quality:
- ✅ Inline comments explaining design decisions
- ✅ Modular structure (agent, logging, instructions, integration)
- ✅ No hardcoded credentials (all via
.env) - ✅ Proper use of ADK types and MCP protocols
Documentation (20 points):
- ✅ README.md with all required sections
- ✅ Problem statement and solution
- ✅ Architecture diagrams and explanations
- ✅ Detailed setup instructions
- ✅ Usage examples and workflow diagrams
Effective Use of Gemini (5 points):
- ✅ Powered by Gemini 2.5 Flash
- ✅ Context caching for optimization
- ✅ Advanced prompt engineering
Agent Deployment (5 points):
⚠️ Not deployed to Agent Engine (local development focus)- ✅ Deployment-ready architecture with environment-based config
YouTube Video Submission (10 points):
⚠️ To be created (recommended structure provided in README)
For the YouTube submission (under 3 minutes):
0:00-0:30 - Problem Statement
- Show overwhelming Canvas assignment list
- Demonstrate planning paralysis scenario
0:30-1:00 - Why Agents?
- Compare traditional task manager vs. Align
- Highlight autonomous multi-tool orchestration
1:00-1:30 - Architecture
- Show architecture diagram
- Explain agent workflow with animations
1:30-2:30 - Demo
- Live demo: "Help me prepare for my CS 101 midterm"
- Show agent fetching assignments, creating plan, scheduling sessions
- Display final Coda document and calendar events
2:30-3:00 - The Build
- Mention Google ADK, Gemini 2.5 Flash, MCP protocol
- Show Langfuse observability dashboard
- Call to action
This project was built for the Google ADK Hackathon. Contributions, suggestions, and feedback are welcome!
MIT License - See LICENSE file for details
- Google ADK team for the excellent framework and documentation
- MCP protocol creators for standardized tool integration
- Langfuse for observability infrastructure
- Canvas, Coda, Exa, and Tavily for their APIs
Built with ❤️ using Google ADK and Gemini 2.5 Flash