بهترین شیوه‌های تعامل

افراد انتظار دارند agent در همان جریان کاری Pulse پاسخ دهد: درخواست را تأیید کند، پیشرفت معنادار گزارش دهد، به پیگیری‌ها واکنش نشان دهد و نتیجه‌ای بگذارد که assignee انسانی بتواند بررسی کند.

پیشنهادها

وقتی وب‌هوک created می‌رسد، امضا را بررسی کنید، data.event_id را ثبت کنید و ظرف ۵ ثانیه پاسخ 2xx بدهید. اجرا را در job پس‌زمینه شروع کنید. نخستین activity را به‌شکل thought کوتاه بفرستید تا شخص ببیند برنامه درخواست را گرفته است.

اگر Issue تفویض‌شده در backlog یا todo است، هنگام شروع کار آن را به in_progress ببرید. برنامه می‌تواند بعداً آن را به qa ببرد، اما نمی‌تواند Issue را ببندد. assignee انسانی را در جریان بگذارید و با responseای پایان دهید که تغییرات، کار باقی‌مانده و موردنیاز برای بازبینی را روشن کند. برنامه نمی‌تواند تفویض خودش را تغییر دهد.

در اجرای طولانی فقط وقتی اطلاعات مفیدی دارید پیشرفت را گزارش کنید. برای وضعیت موقت از thought یا action گذرا استفاده کنید؛ activity بعدی جای آن را در پنل می‌گیرد، اما آن را از سابقه پاک نمی‌کند.

Activityهای agent

Commentهای Issue ممکن است پس از خوانده‌شدن ویرایش شوند. Activityها درخواست‌ها و پاسخ‌ها را همان‌طور که session دریافت کرده، همراه با نویسنده، seq و زمان نگه می‌دارند. گفتگو را از GET /api/v1/agent-sessions/{session_id}/activities بازسازی کنید و به‌جای بازخوانی Commentها با after_seq ادامه دهید.

Activity را متناسب با موقعیت انتخاب کنید: thought برای تأیید، action برای کار انجام‌شده، elicitation برای سؤال، response برای نتیجه و error برای مانع. رمز و خروجی خصوصی ابزار را در activity نگذارید؛ کسانی که Issue را می‌خوانند ممکن است session را هم بخوانند. هنگام retry همان Idempotency-Key را نگه دارید.

وب‌هوک‌های بیشتر

دو action اصلی AgentSessionEvent درخواست تازه و پیگیری را پوشش می‌دهند. رویدادهای بیشتر را فقط وقتی فعال کنید که برنامه به آن‌ها نیاز دارد. تحویل هر رویداد ممکن است تکرار شود؛ پیش از عمل‌کردن، تکراری‌ها را کنار بگذارید.

وب‌هوک‌های Issue و Comment

رویدادهای Issue، Comment و Project در resource_types اختیاری‌اند. وقتی برنامه باید به تغییرات بیرون از session باز واکنش دهد، مثل به‌روزرسانی Issue یا Comment تازه، از آن‌ها استفاده کنید. این رویدادها جای AgentSessionEvent را برای تفویض، منشن یا پاسخ session نمی‌گیرند. Pulse فعلاً دستهٔ وب‌هوک جداگانهٔ اعلان صندوق ورودی برای برنامه‌های agent ندارد.

وب‌هوک‌های تغییر دسترسی

PermissionChange / teamAccessChanged هنگام تغییر تیم‌های نصب توسط ادمین به برنامه خبر می‌دهد. کار روی تیم‌های حذف‌شده را متوقف و نقشهٔ دسترسی محلی را به‌روز کنید. Pulse تفویض آن‌ها را آزاد می‌کند و sessionهای مربوط را با end_reason: team_removed پایان می‌دهد.

{ "type": "PermissionChange", "action": "teamAccessChanged", "data": { "added_team_ids": [], "removed_team_ids": ["68da1fb8af973c6419b9b3f7"] } }

OAuthApp / revoked یعنی نصب حذف شده است. توکن‌هایش را دور بریزید و jobهایش را متوقف کنید؛ برنامه دیگر نمی‌تواند activity نهایی بفرستد. محمولهٔ کامل وب‌هوک‌ها در مرجع آمده است.

یکپارچه‌سازی‌های موجود

چه زمانی یکپارچه‌سازی یا agent بسازیم

وقتی اتصال بیشتر داده را با سرویسی دیگر ردوبدل می‌کند یا از طرف شخص واردشده عمل می‌کند، یکپارچه‌سازی معمولی مناسب است. وقتی افراد باید Issue را به کاربر application مجزا تفویض یا او را @منشن کنند و کارش را در agent session دنبال کنند، برنامهٔ agent بسازید. اقدامات برنامه با هویت خودش و دسترسی محدود به نصب ثبت می‌شوند.

تبدیل یکپارچه‌سازی موجود

Pulse یکپارچه‌سازی نصب‌شده را درجا به برنامهٔ agent تبدیل نمی‌کند. برنامهٔ agent تازه ثبت کنید، URL بازگشت OAuth و گیرندهٔ وب‌هوک امضاشده بدهید و از ادمین بخواهید نصبش کند. فقط کار و مجوزهای لازم را منتقل کنید؛ توکن شخصی را به‌عنوان توکن برنامه به کار نبرید. راهنمای شروع مسیر نصب را توضیح می‌دهد.

بازخورد، درخواست‌ها و سؤال‌ها

پیش از دعوت افراد، نصب، تفویض، منشن، نخستین activity، اجرای طولانی، پیگیری، elicitation، Stop، حذف تیم و حذف نصب را بررسی کنید. اگر payload یا رفتاری مبهم است، نوع رویداد، webhook_id و نمونهٔ پالایش‌شده را ثبت کنید تا بررسی شود. توکن و secret امضا را در گزارش نگذارید. مرجع API محموله‌ها و کدهای خطا را دارد.