تأیید انسانی برای عامل‌ها بسازید؛ توقف را فقط پیش از کار پرخطر بگذارید

برای ساخت تأیید انسانی در یک عامل، گیت را میان پیشنهاد فراخوانی ابزار و اجرای واقعی آن بگذارید. عامل می‌تواند اطلاعات را جمع کند و اقدام را آماده سازد، اما پیش از پرداخت، حذف، ارسال پیام بیرونی یا تغییر حساس باید درخواست را به بازبین نشان دهد و وضعیت اجرا را برای ادامهٔ همان جریان نگه دارد.

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

کدام اقدام به تأیید نیاز دارد؟

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

• تأیید همیشگی: پرداخت، استرداد وجه، حذف غیرقابل‌بازیابی، ارسال یا انتشار بیرونی و تغییر دسترسی یا تنظیمات حساس. اثر چنین اقدام‌هایی می‌تواند از گفت‌وگوی عامل فراتر برود و بازگرداندنشان دشوار باشد.
• تأیید مشروط: تغییرهای محدود و پیام‌هایی که خطرشان به گیرنده، مبلغ یا دامنهٔ داده بستگی دارد. برای نمونه، ذخیرهٔ پیش‌نویس می‌تواند آزاد باشد، اما ارسال همان متن به گیرندهٔ بیرونی متوقف شود.
• بدون توقف انسانی: خواندن داده در محدودهٔ مجوز عامل، محاسبه و تهیهٔ پیش‌نویسی که هنوز اثر بیرونی ندارد. کنترل دسترسی عادی همچنان باید بر این کارها اعمال شود.

این تقسیم‌بندی یک تصمیم طراحی است و چارچوب آن را به‌جای شما تعیین نمی‌کند. برای هر ابزار مشخص کنید کدام آرگومان‌ها خطر را تغییر می‌دهند و در صورت نبودن اطلاعات لازم، فراخوانی را به بازبینی بفرستید. قاعده‌ای که نمی‌تواند گیرنده یا دامنهٔ تغییر را تشخیص دهد، مبنای مطمئنی برای عبور خودکار نیست.

درخواست بازبینی را به وضعیت ذخیره‌شده وصل کنید

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

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

اگر چند فراخوانی هم‌زمان منتظر پاسخ‌اند، تصمیم هر کدام باید به همان فراخوانی برسد. در ثبت تصمیم نیز آرگومان‌های اولیه، پاسخ بازبین و آرگومان‌های نهایی را از هم جدا نگه دارید؛ وگرنه پس از ویرایش روشن نخواهد بود چه چیزی پیشنهاد شده و چه چیزی واقعاً اجازهٔ اجرا گرفته است.

توقف و ادامه در OpenAI Agents SDK

در راهنمای تأیید OpenAI Agents SDK، گزینهٔ needs_approval می‌تواند تأیید را برای همهٔ فراخوانی‌های یک ابزار الزامی کند یا با تابعی دربارهٔ هر فراخوانی تصمیم بگیرد. وقتی تأیید لازم است، اجرای عامل متوقف می‌شود و درخواست‌ها در interruptions قرار می‌گیرند. نتیجه را با result.to_state() به RunState تبدیل کنید، تصمیم را با state.approve(...) یا state.reject(...) ثبت کنید و اجرا را با Runner.run(agent, state) ادامه دهید.

برای بازبینی‌ای که ممکن است پس از پایان فرایند جاری انجام شود، وضعیت را با to_json() یا to_string() ذخیره و هنگام دریافت تصمیم بازسازی کنید. وضعیت سریال‌شده آرگومان ابزار و تصمیم‌های تأیید را نیز در بر می‌گیرد؛ بنابراین باید در محل قابل‌اعتماد بماند. بازسازی وضعیت، اصالت داده یا اختیار فردی را که پاسخ داده است بررسی نمی‌کند و این کنترل‌ها بر عهدهٔ برنامه‌اند.

تابع شرط تأیید فقط زمانی فراخوانده می‌شود که آرگومان‌ها قابل بررسی باشند. اگر آرگومان وجود نداشته باشد یا JSON نامعتبر یا نامناسب باشد، فراخوانی برای بازبینی دستی متوقف می‌شود؛ تأیید چنین درخواستی نیز خطای آرگومان را به ورودی معتبر تبدیل نمی‌کند. این رفتار مانع آن می‌شود که قاعدهٔ مشروط، یک ورودی نامفهوم را ناخواسته از گیت عبور دهد.

در این مسیر، RunState تصمیم مستقیمِ پذیرش یا رد را ثبت می‌کند. اگر بازبین بخواهد گیرنده، مبلغ یا متن را تغییر دهد، فراخوانی قدیمی را تأیید نکنید: آن را رد کنید و پیشنهاد اصلاح‌شده را از مسیر برنامه یا با درخواست پیشنهاد دوباره از عامل وارد جریان کنید. آرگومان تازه باید همان اعتبارسنجی و سیاست تأیید را طی کند.

توقف و ادامه در LangGraph

در مستندات وقفهٔ LangGraph، فراخوانی interrupt() گراف را در نقطهٔ انتخابی متوقف می‌کند و checkpointer وضعیت را نگه می‌دارد. برای ادامه، همان thread_id را به کار ببرید و پاسخ بازبین را با Command(resume=...) بفرستید؛ مقدار پاسخ به فراخوانی وقفه در گره برمی‌گردد. برای توقف طولانی، checkpointer باید در ذخیره‌سازی پایدار باشد، زیرا نگهداری وضعیت فقط در حافظه با پایان فرایند دوام نمی‌آورد.

گره‌ای که وقفه در آن رخ داده، هنگام ادامه از ابتدای همان گره اجرا می‌شود. پس پرداخت، ارسال پیام یا تغییر رکورد را پیش از interrupt() در آن گره انجام ندهید؛ چنین اثری ممکن است دوباره اجرا شود. گرهٔ تصمیم را از گرهٔ اجرای اقدام جدا کنید و برای فراخوانی بیرونی نیز شناسهٔ یکتا و سازوکار جلوگیری از اثر تکراری در نظر بگیرید.

اگر عامل را با لایهٔ LangChain ساخته‌اید، راهنمای میان‌افزار LangChain تنظیم توقف برای ابزارها و تصمیم‌های approve، edit و reject را توضیح می‌دهد. این میان‌افزار برای نگه‌داشتن وضعیت میان توقف و ادامه به checkpointer نیاز دارد. در ویرایش، بازبین اقدام اصلاح‌شده را با نام ابزار و آرگومان‌های تازه می‌فرستد؛ در رد، ابزار اجرا نمی‌شود و بازخورد به عامل می‌رسد.

پس از تصمیم، فقط اقدام مجاز را اجرا کنید

پذیرش باید به آرگومان‌هایی محدود بماند که بازبین دیده است. اگر ویرایش، گیرنده یا مبلغ را عوض کند، سیاست خطر را روی مقدار نهایی دوباره اعمال کنید؛ ممکن است اقدام اصلاح‌شده به سطح دیگری از تأیید نیاز داشته باشد. همچنین مجوز بازبین برای دیدن درخواست، لزوماً مجوز او برای تصویب هر دامنه‌ای از تغییر نیست.

رد باید روشن کند که اقدام انجام نشده است و عامل پس از آن چه اختیاری دارد: کنار گذاشتن کار، درخواست توضیح از کاربر یا ارائهٔ پیشنهاد تازه. در یک مثال فرضی، عامل پیام بیرونی را آماده می‌کند، گیت پیش از ارسال توقف می‌دهد و بازبین گیرنده و متن را می‌بیند. اگر متن ویرایش شود، نسخهٔ نهایی دوباره بررسی می‌شود؛ اگر درخواست رد شود، هیچ پیامی از آن فراخوانی ارسال نمی‌شود.

در نهایت، ثبت اجرای ابزار را از ثبت درخواست تأیید جدا نگه دارید. ممکن است درخواستی پذیرفته شود اما اجرای ابزار بعداً خطا بدهد، یا پاسخی تکراری پس از ادامهٔ جریان برسد. برای اقدام‌های دارای اثر بیرونی، شناسهٔ یکتای عملیات و ثبت نتیجهٔ واقعی کمک می‌کند برنامه تشخیص دهد کدام فراخوانی اجرا شده و آیا تلاش دوباره مجاز است.