לחבר AI ל-Gmail: המכסה של 100 משתמשים שתופסת כל פרויקט חדש

מפתח שבונה סוכן AI שמתחבר ל-Gmail, בודק אותו על עצמו ועל כמה חברים, ואז מגלה כמה חודשים אחר כך שהוא לא יכול להוסיף משתמשים חדשים בכלל - לא נתקל בבאג. הוא פשוט הגיע למכסה קבועה של 100 משתמשים שחלה על כל פרויקט שמבקש הרשאות Gmail בלי לעבור אימות רשמי מול Google.

מכסת שימוש: יחידות, לא בקשות

לפי Google, ה-Gmail API מוגבל ב-1,200,000 יחידות מכסה בדקה לכל פרויקט, ו-6,000 יחידות בדקה לכל משתמש בתוך הפרויקט. לא כל קריאת API שווה ליחידה אחת: שליחת מייל (messages.send) עולה 100 יחידות, קבלת מייל בודד (messages.get) עולה 20, ורשימת הודעות (messages.list) עולה רק 5. סוכן AI שקורא תיבת דואר עמוסה ומעבד כל מייל בנפרד יכול לצבור מכסה מהר יותר ממה שנראה על הנייר - 300 מיילים שנקראים אחד-אחד כבר צורכים 6,000 יחידות, בדיוק על סף המכסה למשתמש בדקה.

אימות OAuth: לא שלב בירוקרטי אופציונלי

לפי Google, אפליקציה שמבקשת הרשאה רגישה כמו קריאת Gmail, בלי לעבור את תהליך אימות ה-OAuth הרשמי, מוצגת למשתמשים עם מסך אזהרת "אפליקציה לא מאומתת" - וברגע שהמסך הזה מופיע, האפליקציה מוגבלת ל-100 משתמשים חדשים בסך הכל, לכל חיי הפרויקט. זו לא מגבלה חודשית שמתאפסת - היא קבועה, ולא ניתן לעקוף אותה ביצירת מזהה OAuth client חדש או פריסה מחדש של האפליקציה.

מה זה אומר בפועל לתכנון פרויקט

עבור פרויקט פנימי (כלי לצוות של 10 אנשים), המכסה של 100 משתמשים לרוב לא רלוונטית בכלל - אפשר להישאר במצב "לא מאומת" בלי בעיה. אבל עבור מוצר שמיועד לצמוח מעבר לכמה עשרות משתמשים, תהליך האימות מול Google (אימות בעלות על דומיין, פרטי מדיניות פרטיות, לפעמים ביקורת אבטחה) צריך להתחיל מוקדם - הוא לוקח שבועות, לא ימים, ולא משהו שרוצים לגלות שצריך כשכבר יש 95 משתמשים רשומים וממתינים.

מה בפועל צריך בקוד

לחיבור AI ל-Gmail, הזרימה הטכנית: משתמש מאשר גישה דרך מסך OAuth, מקבלים access token עם ההרשאות (scope) הספציפיות שביקשתם - gmail.readonly לקריאה בלבד, gmail.send לשליחה, gmail.modify לשניהם - ומשתמשים בטוקן כדי לקרוא ל-Gmail API. ה-AI עצמו (למשל Claude API) נכנס בשלב שאחרי: הטקסט של המייל מגיע כתוצאה מ-messages.get, עובר לניתוח או ניסוח דרך המודל, והתשובה חוזרת דרך messages.send בהרשאה הנפרדת שביקשתם לכך.

מקרה קצה: סוכן שקורא תיבה גדולה בפעם הראשונה

סוכן AI שמתחבר לתיבה קיימת עם אלפי מיילים היסטוריים ומנסה "לסרוק הכל" בפעם הראשונה - למשל כדי לבנות תמונה ראשונית או לאנדקס תוכן - עלול לפגוע במכסה הדקתית מהר מאוד, כי כל קריאת messages.get עולה 20 יחידות ו-300 קריאות כאלה כבר מתקרבות ל-6,000 היחידות המותרות למשתמש בדקה. הפתרון המעשי הוא לא לנסות "לקרוא הכל בבת אחת", אלא לעבד בקבוצות (batches) עם השהיה מחושבת ביניהן, ולהשתמש ב-messages.list (5 יחידות בלבד) כדי לקבל תחילה רשימת מזהים, ורק אז לגשת בפועל לתוכן המיילים שבאמת רלוונטיים.

דוגמה: תכנון תור בקשות פשוט

במקום לתת לסוכן AI לקרוא ל-API בכל פעם שהוא "מרגיש צורך", כדאי לבנות תור בקשות פשוט בקוד: הודעות נכנסות נאספות, ומעובדות בקבוצות של, למשל, 50 בכל פעם, עם השהיה של שנייה בין קבוצות. זה שומר את הצריכה הרבה מתחת למכסה של 6,000 יחידות לדקה למשתמש, גם כשהתיבה עמוסה ופעילה - ומונע מצב שבו הסוכן פשוט "נתקע" עם שגיאת מכסה בדיוק כשהוא באמצע עיבוד חשוב.

איפה AI עצמו לא פותר בעיית הרשאות

חשוב להבין: שום שיפור בפרומפט או במודל ה-AI לא עוקף את מגבלות ה-OAuth או המכסה - אלה חסמים ברמת התשתית של Google, לא ברמת האיכות של הסוכן. מפתח שמנסה "לתקן" שגיאת מכסה על ידי שינוי הפרומפט של המודל פשוט מבזבז זמן על השכבה הלא נכונה - הפתרון תמיד נמצא בקוד שמנהל את קצב הבקשות ובתהליך האימות מול Google, לא בהוראות שנותנים למודל עצמו.

מה לנסות עכשיו

לפני שמתחילים לפתח אינטגרציית Gmail, להחליט מראש: האם זה כלי פנימי לקבוצה קטנה (אין צורך באימות), או מוצר שמיועד לצמוח (להתחיל את תהליך האימות מול Google מוקדם, לא אחרי שמכת 100 המשתמשים כבר קרובה). וכשמבקשים scope, לבקש את המינימלי הנדרש בפועל - gmail.readonly במקום gmail.modify כשלא צריך לכתוב, כי scope רחב יותר גם מגדיל את הסיכון בתהליך האימות עצמו ומאריך את הזמן עד שהאפליקציה מאושרת לשימוש בלי הגבלת משתמשים.