From Automation to Agent: How to Upgrade Your Birthday Notifier with AI Gift Suggestions

If you followed my last guide, you now have a fantastic automated system: the AI-Powered Birthday Notification System. It runs daily, checks your spreadsheet, and generates a personalized birthday message using the Gemini API.

But why stop at automation? We can transform this passive reporter into a simple AI Agent that solves the next most common problem: What gift should I buy?

By giving the system a second, complex task, generating thoughtful gift recommendations based on the person's interests we dramatically increase its value and push it into agent territory.

We're moving beyond simple automation. This guide helps you build a sophisticated AI Agent, a tool that actively manages your key relationships by performing two critical, contextual tasks on two different days: sending gift suggestions 14 days early, and providing a personalized message on the birthday.

This is the complete, start-to-finish guide for setting up your Two-Stage AI-Powered Birthday Notification System using Google Sheets, Google Apps Script, and the Gemini API.

 The Agent's Architecture

Our Agent relies on three core, integrated components:

1. Google Sheets (The Data): Holds names, dates, and tracks two separate sent dates (message and gift).

2. Google Apps Script (The Engine): Runs daily, checks two different dates (Today and 14 Days Out), and manages the two separate email sends.

3. Gemini API (The Intelligence): Generates two distinct outputs: a personalized birthday message and thoughtful gift recommendations.

Phase 1: Data Foundation (Google Sheets)

Your spreadsheet is the brain of the Agent. We need to add a crucial column to track the gift reminders separately.

Step 1: Create and Name Your Sheet

1. Go to Google Sheets and create a new spreadsheet. Name it Birthday AI Reminder.

2. Rename the first tab (sheet) to exactly: Birthdays. This name must match the code exactly!

Step 2: Define and Input Your Data (CRITICAL UPDATE)

You must include all six columns below. Column F is new and vital for the two-stage logic.

Column	Header	Example Value	Purpose
A	Name	Jane Doe	The person's full name.
B	Birthday (MM/DD)	11/25	The month and day (MUST include the leading zero).
C	Classification	3	A number for the relationship category.
D	Last Sent Year	2024	Managed by the Agent! Tracks if the birthday message was sent this year.
E	Notes/Context	Loves gardening and has a pet cat named Miso.	CRITICAL: Context used by the AI for personalized messages AND gift ideas.
F	Last Gift Sent Year	2024	NEW! Tracks if the gift reminder was sent this year.

Classification Key (Column C) and Agent Logic:

• 1 (Close Family) & 3 (Close Friends): Receives AI Gift Suggestion (14 Days Early) + AI Message (On Birthday).

• 2 (Extended Family) & 4 (Friends): Receives AI Message Only (On Birthday).

• 5 (Deceased): Receives AI Reflective Message Only (On Birthday).

Phase 2: Code Integration (Google Apps Script)

This is the logic that executes the two-stage check and the two parallel API calls.

Step 3: Open Apps Script

1. In your Birthday AI Reminder spreadsheet, go to Extensions > Apps Script.

2. This opens the code editor. Delete any placeholder text in the Code.gs file.

Step 4: Paste the Complete Agent Code

Copy the complete, working script below and paste it into the empty Code.gs file.

Important: Before saving, find the line const RECIPIENT_EMAIL = "CHANGE THIS TO YOUR EMAIL ADDRESS"; and replace the placeholder with your actual email address.

$$Insert the complete `birthday-notifier-two-stage-agent.js` file content here$$

Birthday Agent Code.pdf

Download PDF • 134KB

Phase 3: Configuration (API Key & Authorization)

Since you have already set up the API Key in the previous guide, this section focuses on verification and initial authorization.

Step 5: Verify Your Gemini API Key and Permissions

1. Verify API Key: In your Apps Script editor, go to the Project Settings (gear icon) on the left sidebar. Scroll down to Script properties and confirm that the GEMINI_API_KEY is present and correct.

2. Run Authorization: The script needs permissions (to connect externally and send email). You must grant them once. In the Apps Script editor, select the function mainDailyCheck from the dropdown menu at the top and click the Run button.

3. Grant Permissions: If prompted, follow the steps to select your Google account, click Advanced, and then Allow all permissions.

Phase 4: Launch and Automation (The Daily Trigger)

This final step schedules your Agent to run every day.

Step 6: Create the Daily Trigger (CRUCIAL STEP)

Since we renamed the main scheduler function to mainDailyCheck() to handle the two-stage logic, you must run the trigger setup function again to update your schedule.

1. In the Apps Script editor, select the function createDailyTrigger from the dropdown menu at the top.

2. Click the Run button.

This will delete any old triggers and set the script to run the mainDailyCheck function every day between 7:00 AM and 8:00 AM. Your Agent is now fully operational!

Troubleshooting & Debugging

• "AI generation failed": The API key or connection failed. Run the testApiKey function (select it in the dropdown and click Run) and check the logs. If it reports failure, re-verify your key.

• "No Gift Suggestions": Check the Classification (Column C) in your sheet. Only 1 (Close Family) and 3 (Close Friends) receive gift ideas.

• "I got the gift email, but not the birthday message": Check that you entered a date into the Last Sent Year column (D) for the birthday message to be sent, and a date into the Last Gift Sent Year (F) for the gift suggestion to be sent. The Agent needs to know when the last event occurred for both.

• Note you can open Gemini and use it to debug any issues

And there you have it - a complete Birthday Agent.

For the full guide:

A Guide to Building a Complete AI Birthday Agent.pdf

Download PDF • 4.08MB

Code:

Birthday Automation Code:

Birthday Automation Code.pdf

Download PDF • 3.95MB

Birthday Agent Code:

Birthday Agent Code.pdf

Download PDF • 134KB