قرارداد اجرای ایجنت را قبل از انتخاب فریمورک بنویس
هر فصل یک نفر در تیم می‌پرسد روی کدام فریمورک ایجنت استاندارد شویم. سؤال معمولاً زود است. از قبل سه رانر نیمه‌تمام در مونوریپو داریم، دو بسته پرامپت رهاشده، و صفحه‌ای با عنوان پلتفرم ایجنت که بعد از استندآپ کسی بازش نمی‌کند.
فکر نمی‌کنم قطعه گم‌شده SDK دیگر باشد. قطعه گم‌شده قرارداد نازک و نسخه‌دار است برای اینکه یک اجرای ایجنت در سیستم ما چیست. بدون آن، هر فریمورک تازه شش هفته ناجی به نظر می‌رسد، بعد دوباره بازنویسی می‌کنیم چون چسب قدیمی هیچ‌وقت چیزها را دو بار با یک اسم نام نبرده.
چه چیزی مدام از نو اختراع می‌شود
به سه آزمایش آخر ایجنت در یک فروشگاه فول‌استک معمولی نگاه کن. ارائه‌دهنده مدل متفاوت. رجیستری ابزار متفاوت. تصور متفاوت از «حافظه». درد زیرین یکی است.
چطور این نشست را در retry یک webhook شناسایی کنم؟ کدام ابزارها هستند و کدام تأیید می‌خواهند؟ ایجنت در sandbox اجازه دارد به چه چیزی دست بزند؟ کدام مصنوع باید بماند تا انسان PR را بازبینی کند؟ وقتی بودجه تمام شد یا لپ‌تاپ خوابید چه می‌شود؟ چطور ادامه بدهم بدون اینکه اثر جانبی را دو بار پخش کنم؟
فریمورک‌ها این سؤال‌ها را با اسم‌های خودشان جواب می‌دهند. صف تو، خط استقرار، و ابزار حادثه هنوز با اسم‌های تو حرف می‌زنند. مالیات بازنویسی لایه ترجمه است، نه صدای مدل.
قراردادی به اندازه کافی نازک که نسخه بخورد
قرارداد را قبل از انتخاب LangGraph، Agents SDK، یا حلقه خانگی می‌نویسم. چیزی نزدیک به این، نه زیرک، فقط واژگان مشترک:
شناسه نشست هویت است. ابزار سطح قابلیت است. مجوز sandbox و شبکه را محدود می‌کند. نقطه تأیید ایست بازرسی انسان است، نه شعار مبهم انسان در حلقه. مصنوع چیزی است که بازبین بدون بازپخش چت بتواند باز کند. بودجه کلید قطع است. نشانه ادامه راهی است که webhook یا UI دوباره وصل شود بدون اینکه WebSocket منبع حقیقت باشد.
`version` را در schema بگذار. وقتی فیلدی اضافه می‌کنی که معنای ادامه را عوض می‌کند، نسخه‌اش را بالا ببر. این یک عادت از یک مهاجرت فریمورک دیگر بهتر است.
چرا فریمورک تاوان شکست قرارداد را می‌دهد
وقتی اجرا بعد از استقرار ادامه پیدا نمی‌کند، می‌گویند «فریمورک نابالغ است». گاهی راست است. اغلب اپ هرگز نشانه ادامه را ماندگار نکرده، هرگز ذخیره نکرده کدام صدای ابزار schema را عوض کرده، و هرگز ثبت نکرده تأیید آرگومان نهایی را پوشش می‌داده یا پیش‌نویس را. این شکاف قرارداد است.
وقتی دو تیم نمی‌توانند یک ایجنت را شریک شوند، می‌گویند «پلتفرم می‌خواهیم». گاهی راست است. اغلب یک تیم ابزار را تابع آزاد می‌داند و تیم دیگر سرور MCP با اسم مجوز متفاوت. همان ایده، لبه بدون نسخه.
وقتی eval با پروداکشن نمی‌خواند، مدل را مقصر می‌دانند. گاهی منصفانه است. اغلب هارنس eval هرگز همان مجوز، بودجه، یا سیاست تأییدی را ندیده که webhook پروداکشن اعمال می‌کند. ایجنت دیگری را ارزیابی کرده‌ای.
قاعده‌هایی که بعد از برخورد با واقعیت مانده‌اند
قرارداد را کوچک‌تر از فریمورک نگه دار. اگر نوع به سیستم افزونه نیاز دارد، زیاد ساخته‌ای.
مفهوم فریمورک را در یک ماژول آداپتور روی اسم‌های خودت بنشان. نگذار شیء حافظه فروشنده به محموله صف نشت کند. نگذار شناسه نشست فروشنده تنها شناسه تو باشد اگر webhook از قبل شناسه همبستگی دارد.
نقطه تأیید را روی کار برگشت‌ناپذیر بگذار: نصب وابستگی، مهاجرت، باز کردن PR، نام مستعار استقرار، هر چیزی که پول خرج می‌کند یا راز را می‌چرخاند. خواندن ریپو و اجرای تست واحد نباید انسان را پیج کند.
مصنوع را حتی وقتی رونوشت بزرگ است ماندگار کن. چت چهل‌پیامی در حادثه شواهد ضعیفی است. diff ذخیره‌شده، لاگ تست، و گزارش eval قابل استفاده‌اند.
بودجه اختیاری نیست. ایجنت اگر بگذاری روی تست ناپایدار توکن می‌سوزاند. گام و ساعت دیواری را همان‌طور سقف بگذار که job در CI را سقف می‌گذاری.
فریمورک را بعد از وجود رابط انتخاب کن
وقتی قرارداد کسل شد، انتخاب فریمورک آسان‌تر می‌شود. زمان اجرایی را ترجیح بده که ادامه، تأیید، و خروج مصنوع را بدون چسب قهرمانانه احترام کند. آن را ترجیح بده که استقرار و صف تو از قبل شبیهش هستند. آن را رد کن که مجبورت می‌کند `sessionId` را رها کنی چون داشبوردشان اسم قشنگ‌تری دارد.
ترجیح می‌دهم قرارداد چهل‌خطی را نگه دارم و رانر را عوض کنم تا با فریمورکی ازدواج کنم که مدل ذهنی‌اش هیچ‌وقت با webhook، sandbox، یا جریان بازبینی ما نخوانده. صنعت فریمورک ایجنت را ادامه خواهد داد. اشکالی ندارد. اول قرارداد را نسخه بزن تا بازنویسی‌ها کوچک شوند، یا دیگر لازم نباشند.
اسم فریمورک را در مقاله قفل نکن. چیزی که امروز در اکوسیستم رایج است فردا اسمش عوض می‌شود. قرارداد تو نباید به آن اسم بند باشد.
قرارداد را در صف تمرین کن، نه در اسلاید
یک اجرای مصنوعی بساز که وسط کار قطع شود: webhook دوباره بیاید، تأیید یک بار ثبت شود، و worker دوم همان اثر را تکرار نکند. اگر این سناریو را فقط در سند نوشته‌ای، هنوز قرارداد نداری. فیلدهایی که این سناریو لازم دارد همان فیلدهایی هستند که باید نسخه بخورند.
خروجی این تمرین معمولاً کوتاه است. نشانه ادامه، وضعیت تصمیم، و شناسه اثر انجام‌شده. اگر برای پاس کردن تمرین مجبور شدی شیء داخلی فریمورک را در صف ذخیره کنی، آداپتور را نازک نکرده‌ای. صف باید اسم‌های خودت را حمل کند تا فردا رانر عوض شود و پیام قدیمی هنوز قابل خواندن بماند.
پرسش‌های کوتاه
**پس اصلاً فریمورک نگیرم؟** بگیر، بعد از اینکه اسم‌های خودت را نوشتی. فریمورک پیاده‌سازی قرارداد است نه جایگزینش.
**قرارداد چند فیلد داشته باشد؟** به اندازه سؤال‌هایی که سه آزمایش قبلی را سوزاندند. اگر به افزونه نیاز دارد زیادی است.
**eval چرا با پروداکشن فرق می‌کند؟** چون مجوز و بودجه و تأیید را در هارنس ندیده‌ای. همان ایجنت را ارزیابی نکرده‌ای.