حساب‌های Agent در Nylas هویت تقویمی مستقل به عامل‌های هوش مصنوعی دادند

یک عامل هوش مصنوعی که می‌تواند ایمیل بنویسد اما قادر نیست زمانی را در تقویم رزرو کند، تنها نیمی از کاربردش را دارد. تصور کنید در لحظه‌ای که گفتگو به «بیایید پنجشنبه ساعت ۲ همدیگر را ببینیم» می‌رسد، عامل شما به جای ارسال یک پیام متنی ساده، یک دعوت‌نامه رسمی بفرستد که کاربر در گوگل کَلندر (Google Calendar) یا اوت‌لوک (Outlook) آن را دریافت و تأیید کند. این سیستم باید بتواند دعوت‌نامه‌ها را به آدرس خودش دریافت کند و پاسخ (RSVP) دهد تا سازمان‌دهنده جلسه، پاسخ واقعی عامل را در کنار سایر شرکت‌کنندگان ببیند.

طبق اعلام Nylas، این سیستم به‌جای چسباندن یک کتابخانه زمان‌بندی ساده به یک صندوق پستی مشترک، یک «حساب عامل» (Agent Account) مستقل فراهم می‌کند. این حساب یک تقویم اصلی (Primary Calendar) دارد که به‌عنوان یک «شهروند درجه‌یک» در اکوسیستم‌های گوگل و مایکروسافت عمل می‌کند. در واقع، رویکرد Nylas عامل را از یک «هماهنگ‌کننده مبتنی بر متن» به یک «شرکت‌کننده واقعی در تقویم» تبدیل می‌کند که قادر است دعوت‌نامه‌های رسمی iCalendar را ارسال، دریافت و ردیابی کند.

این تحول در حالی رخ می‌دهد که اکثر سیستم‌های فعلی هوش مصنوعی تنها زمان‌ها را در متن پیشنهاد می‌دهند و امیدوارند کاربر به‌صورت دستی آن را به تقویم خود اضافه کند. این موضوع یک «شکاف اصطکاکی» ایجاد می‌کند، زیرا عامل هیچ آگاهی لحظه‌ای از تعهدات و زمان‌های اشغال‌شده‌ی خود ندارد. همان‌طور که در تحلیل‌های قبلی ما درباره‌ی استفاده از ابزار (Tool Use) اشاره کردیم، هدف نهایی این است که عامل‌ها بتوانند تغییرات دنیای واقعی را بدون دخالت انسان مدیریت کنند. در همین راستا، برای عبور از موانع عملیاتی در پیاده‌سازی این قابلیت‌ها، می‌توان از ۷ ابزار کلیدی برای حل بن‌بست‌های اجرای عامل‌ها بهره برد تا تعامل با دنیای واقعی دقیق‌تر شود.

حساب‌های Agent (Agent Accounts) — شبیه به دادن یک پاسپورت و دفترچه یادداشت مستقل به یک دستیار دیجیتال تا خودش مسئولیت برنامه‌ریزی را بپذیرد — اکنون یک تقویم اصلی دارند که به‌صورت خودکار ایجاد می‌شود. بر اساس مستندات فنی، این تقویم اصلی تا زمانی که سایر تقویم‌ها روی حساب موجود باشند، قابل حذف نیست. این تقویم از طریق نقاط انتهایی (Endpoints) استاندارد /v3/grants/{grant_id}/ در دسترس است؛ این بدان معناست که کدهایی که پیش‌تر برای حساب‌های انسانی نوشته شده‌اند، بدون هیچ تغییری روی حساب‌های عامل هم کار می‌کنند.

توسعه‌دهندگان می‌توانند برای تفکیک وظایف و مدیریت بهتر، تقویم‌های اضافی بسازند. برای مثال، یک عامل می‌تواند یک تقویم اختصاصی برای «تماس‌های فروش» و یک تقویم مجزا برای «امور داخلی» روی یک حساب واحد داشته باشد (البته با رعایت سقف تعیین‌شده در طرح اشتراکی). برای جلوگیری از تداخل زمانی یا رزرو همزمان (Double-booking)، سیستم پرس‌وجوهای free/busy را ارائه می‌دهد که بلوک‌های زمانی اشغال‌شده برای هویت آن عامل را در یک بازه زمانی مشخص برمی‌گرداند.

به گزارش Nylas، مدیریت این هویت‌ها از طریق ابزارهای API و CLI انجام می‌شود. من شخصاً روی CLI کار می‌کنم، بنابراین دستورات ترمینالی که در اینجا شرح می‌دهم، همان‌هایی هستند که در یک جریان کاری واقعی بیشترین کاربرد را دارند:

• لیست تقویم‌ها (Calendar Listing): توسعه‌دهندگان می‌توانند لیست تقویم‌ها را از طریق ترمینال با دستور nylas calendar list یا از طریق API با متد GET /v3/grants/{grant_id}/calendars دریافت کنند. هر دو روش، تقویم اصلی و هرگونه تقویم اضافی را برمی‌گردانند.
• بازیابی رویدادها (Event Retrieval): متد GET /v3/grants/{grant_id}/events لیست رویدادهای یک تقویم را نمایش می‌دهد. با ارسال پارامتر expand_recurring=true سیستم هر نمونه از یک سری جلسه تکرارشونده را به‌صورت مجزا (Materialize) نمایش می‌دهد، به‌جای اینکه فقط یک قانون تکرار کلی را برگرداند. این قابلیت زمانی حیاتی است که عامل می‌خواهد روزهای خاصی را بررسی کند، نه فقط یک الگوی تکراری را.
• همگام‌سازی تک-مرحله‌ای (One-Shot Sync): برای همگام‌سازی در یک بازه زمانی، متد GET /v3/grants/{grant_id}/events/import تمام رویدادها را از تمامی تقویم‌های حساب در یک محدوده زمانی تعریف شده استخراج می‌کند.
• مشاهده جزئیات در ترمینال: دستور nylas calendar events list رویدادهای آتی را نشان می‌دهد. علاوه بر این، دستور nylas calendar events show <event-id> جزئیات یک رویداد خاص را چاپ کرده و شرکت‌کنندگان آن و وضعیت فعلی RSVP آن‌ها را آشکار می‌کند.

وقتی یک عامل میزبان جلسه است، با ارسال یک درخواست POST به مجموعه رویدادها و فعال کردن notify_participants=true یک دعوت‌نامه واقعی ارسال می‌کند که مستقیماً در اینباکس Gmail یا Outlook شرکت‌کننده قرار می‌گیرد. اگر کاربر گوگل در Gmail روی «Yes» کلیک کند، گوگل پاسخ را به‌طور خودکار بازمی‌گرداند؛ کاربر اوت‌لوک نیز با کلیک بر روی «Accept» همین کار را از طریق مایکروسافت انجام می‌دهد.

هر پاسخ باعث به‌روزرسانی فیلد participants[].status شده و یک وب‌هوک (Webhook) از نوع event.updated فعال می‌کند تا عامل بدون نیاز به تحلیل متن ایمیل (Parsing)، بفهمد چه کسی جلسه را پذیرفته است. مکانیزم iCalendar تضمین می‌کند که عامل در دعوت‌نامه، دقیقاً مانند هر شرکت‌کننده دیگری به نظر برسد.

برای کسانی که با ترمینال راحت‌ترند، CLI نایلس اجازه می‌دهد با دستور nylas calendar events create به‌سرعت رویداد بسازند. این روش با استفاده از پرچم‌ها (Flags) برای عنوان، زمان شروع/پایان و شرکت‌کنندگان، کاربر را از فرمت‌بندی دستی JSON نجات می‌دهد. برای مثال:

nylas calendar events create --title "Product demo" --start "2025-04-11T16:00:00Z" --end "2025-04-11T17:00:00Z" --participant [email protected] --participant [email protected]

در لایه API، این عمل یک درخواست POST به مجموعه رویدادها است. برای نمونه، می‌توانید درخواستی به آدرس https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary&notify_participants=true ارسال کنید که بدنه JSON آن شامل عنوان، شرکت‌کنندگان و بلوک when (با استفاده از Epoch Timestamps برای زمان شروع و پایان) باشد.

در مورد تغییرات، به‌روزرسانی یا لغو یک رویداد باید به تمام شرکت‌کنندگان برسد تا از تداخل‌های زمان‌بندی جلوگیری شود. وقتی عامل سازمان‌دهنده باشد، یک درخواست PUT /v3/grants/{grant_id}/events/{event_id} تغییرات مربوط به زمان، عنوان یا مکان را به تقویم تمام شرکت‌کنندگان می‌فرستد. یک درخواست DELETE نیز لغو جلسه را ارسال کرده و آن را از تقویم مهمان‌ها حذف می‌کند.

در CLI، این موارد توسط دستورات nylas calendar events update و nylas calendar events delete مدیریت می‌شوند. توسعه‌دهندگان باید تنظیم notify_participants را در هر تغییر به‌طور آگاهانه تعیین کنند:

• True: برای هر ایجاد، به‌روزرسانی یا حذف، یک ایمیل ارسال می‌کند. این پیش‌فرض استاندارد برای زمان‌بندی‌های فعال است.
• False: تغییر را به‌صورت خاموش (Silent) اعمال می‌کند. این برای پیش-تنظیم رویدادی که عامل قرار است بعداً اعلام کند یا پر کردن تاریخچه‌ها بدون ارسال پیام برای کاربران مفید است.

عامل‌ها فقط میزبان نیستند، بلکه دعوت‌ها را دریافت می‌کنند. وقتی یک انسان آدرس ایمیل عامل را به یک جلسه اضافه کند، تقویم او دعوت‌نامه‌ای به صندوق پستی عامل می‌فرستد که Nylas آن را تحلیل می‌کند. سپس یک رویداد متناظر در تقویم اصلی عامل ظاهر شده و وب‌هوک event.created فعال می‌شود.

در این حالت، عامل به‌عنوان شرکت‌کننده‌ای با وضعیت noreply لیست شده و سازمان‌دهنده، همان کسی است که دعوت را فرستاده است. این مکانیزم است که تقویم را برای اتوماسیون واقعاً کاربردی می‌کند. توصیه می‌شود توسعه‌دهندگان منطق عامل را کاملاً بر اساس وب‌هوک event.created پیش ببرند. اگرچه وب‌هوک message.created نیز به دلیل رسیدن ایمیل دعوت فعال می‌شود، اما شیء رویداد (Event Object) در حال حاضر تمام اطلاعات لازم شامل سازمان‌دهنده، شرکت‌کنندگان، زمان‌ها و توضیحات را دارد تا عامل تصمیم بگیرد آیا در جلسه شرکت کند یا خیر. بنابراین باید وب‌هوک رویداد را برای منطق زمان‌بندی انتخاب کرد و کپی ایمیلی را نادیده گرفت.

برای پاسخ دادن به یک دعوت‌نامه، عامل باید از نقطه انتهایی send-rsvp (POST /v3/grants/{grant_id}/events/{event_id}/send-rsvp) با وضعیت‌های yes یا no یا maybe استفاده کند.

استفاده از این نقطه انتهایی تنها راه صحیح برای پاسخ است. یک پاسخ ایمیلی ساده به سازمان‌دهنده، بلوک‌های تقویمی او را به‌روز نمی‌کند. تنها یک پاسخ رسمی iCalendar — که از طریق send-rsvp ارسال شود — تضمین می‌کند که پاسخ به سازمان‌دهنده و سایر شرکت‌کنندگان منتقل شود. از دید سازمان‌دهنده، پاسخ عامل دقیقاً مانند هر شرکت‌کننده دیگر (پذیرفته شده، رد شده یا احتمالی) در کنار سایرین ظاهر می‌شود.

در ترمینال، دستور nylas calendar events rsvp <event-id> <status> این کار را انجام می‌دهد. این دستور همچنین از پرچم اختیاری --comment برای افزودن یادداشت به پاسخ پشتیبانی می‌کند، مانند:

nylas calendar events rsvp <event-id> no --comment "I have a conflict"

پس از ارسال RSVP، یک وب‌هوک event.updated روی تقویم خودِ عامل فعال می‌شود تا بتواند تغییر وضعیت خود را ردیابی کند.

قبل از پیشنهاد هر زمانی، عامل باید با استفاده از نقطه انتهایی free-busy (POST /v3/grants/{grant_id}/calendars/free-busy) همراه با زمان شروع، پایان و آدرس ایمیل عامل، استعلام بگیرد. این درخواست، بلوک‌های اشغال‌شده را برمی‌گرداند تا از رزرو همزمان جلوگیری شود.

زمانی که یک عامل چندین تقویم را مدیریت می‌کند، نقطه انتهایی availability (POST /v3/grants/{grant_id}/calendars/availability) مؤثرتر است. این متد به‌جای بازگرداندن بلوک‌های اشغال‌شده خام، پنجره‌های کاندیدای باز (Open Windows) را در تمام تقویم‌های حساب برمی‌گرداند. CLI برای این عملیات دستورات nylas calendar availability check یا nylas calendar find-time را ارائه می‌دهد. گردش کار اصلی این است: ابتدا استعلام تقویم خود عامل، و سپس ایجاد رویداد برای زمانی که می‌دانیم باز است.

در حال حاضر، پیشنهاد زمان جایگزین (Counter-proposing) یک عملیات درجه‌یک در API نیست. اگر یک بازه زمانی پیشنهادی رد شود، الگوی رایج عبارت است از:

1. ارسال RSVP با وضعیت no یا maybe.
2. پاسخ به دعوت‌نامه با پیشنهاد یک زمان جایگزین در متن پیام.
3. ایجاد رویداد جدید پس از موافقت طرف مقابل.

برای عاملی که خودش مذاکره را هدایت می‌کند، بهترین مسیر این است که ابتدا free-busy را استعلام کند، زمانی را که خود باز است پیشنهاد دهد و پس از توافق، رویداد را ایجاد کند.

یک محدودیت مهم وجود دارد: نقاط انتهایی زمان‌بندی میزبان (/v3/scheduling/*) هنوز برای گرنت‌های حساب Agent در دسترس نیستند. در نتیجه، تمام مذاکرات زمانی فعلاً باید از طریق API رویدادها و منطق داخلی توسعه‌دهنده مدیریت شود، نه از طریق یک صفحه زمان‌بندی میزبان. البته وقتی زمان از پیش مشخص باشد، API رویدادها کاملاً کافی است.

در پیاده‌سازی این سیستم، باید از چندین «باگ زمان‌بندی» رایج که انسان‌ها معمولاً به‌صورت غریزی مدیریت می‌کنند، دوری کرد:

• تله حذف (The Deletion Trap): حذف یک رویداد بدون فعال کردن notify_participants=true باعث می‌شود جلسه همچنان در تقویم مهمان‌ها باقی بماند. شما باید لغو را با اعلان ارسال کنید، مگر اینکه دلیل خاصی برای حذف بی‌صدا داشته باشید.
• ابهام منطقه زمانی (Timezone Ambiguity): حساب‌های Agent هیچ منطقه زمانی پیش‌فرضی ندارند. توسعه‌دهندگان باید صریح باشند و از Epoch Timestamps (برای API) یا رشته‌های ISO 8601 (برای CLI) همراه با پرچم اختیاری --timezone استفاده کنند تا از حدس‌های سرور جلوگیری شود.
• سقف کوتای پیام (Quota Limits): هر اعلان در سهم روزانه ارسال پیام حساب محاسبه می‌شود. در طرح رایگان، این مقدار ۲۰۰ پیام در روز است. اگر سقف تکمیل شود، رویداد همچنان ذخیره می‌شود اما دعوت‌نامه به‌صورت بی‌صدا نادیده گرفته می‌شود و هیچ‌کس باخبر نمی‌شود.
• نویز وب‌هوک (Webhook Noise): چون دعوت‌نامه‌ها هم وب‌هوک event.created و هم message.created را فعال می‌کنند، برای جلوگیری از تکرار عملیات، فقط وب‌هوک رویداد باید محرک منطق زمان‌بندی باشد.
• انتشار RSVP: تنها متد send-rsvp به‌عنوان به‌روزرسانی تقویم شناخته می‌شود. یک ایمیل متنی ساده به سازمان‌دهنده، بلوک‌های تقویمی او را تغییر نمی‌دهد.

این جابجایی، عامل هوش مصنوعی را از یک دستیار غیرفعال به یک هماهنگ‌کننده فعال تبدیل می‌کند. با مالکیت هویت تقویمی، عامل اکنون می‌تواند وضعیت دسترسی (Availability) خود را به‌طور پایدار حفظ کند، به‌طوری که توسط هر ارائه‌دهنده بزرگ تقویم در سطح جهانی به رسمیت شناخته شود.

گام بعدی شما

• اگر در حال ساخت عامل‌های Productivity هستید، به‌جای ارسال متن‌های «من ساعت ۴ آزاد هستم»، از API رویدادها برای ثبت مستقیم جلسه استفاده کنید.
• وب‌هوک‌های event.created را جایگزین تحلیل متن ایمیل‌ها برای تشخیص جلسات جدید کنید.
• برای جلوگیری از خطاهای زمانی، تمام ورودی‌های ساعت را به فرمت Unix Epoch تبدیل کنید.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.