انسان در حلقه (Human-in-the-loop) چیست و چرا برای ایجنتها حیاتی است؟
هر ایجنتی که ابزار میزند، در واقع به نام کاربرش در دنیای واقعی اثر میگذارد: پول جابهجا میکند، ایمیل میفرستد، رکورد حذف میکند. تا وقتی خروجی مدل فقط متن است، یک اشتباه قابل تحمل است؛ اما وقتی خروجی مدل مستقیماً به API بانک یا SMTP شما وصل میشود، همان اشتباه به یک حادثهٔ مالی یا اعتباری تبدیل میشود. انسان در حلقه یعنی دقیقاً روی این مرز، یک نقطهٔ کنترل انسانی بگذاریم.
- تأیید یا رد فراخوانی ابزار: مدل درخواست tool_call تولید میکند و انسان قبل از اجرای واقعی تصمیم میگیرد.
- ویرایش وضعیت: انسان آرگومانهای پیشنهادی مدل را اصلاح میکند (مثلاً مبلغ بازپرداخت) و نسخهٔ اصلاحشده اجرا میشود.
- بازبینی خروجی ابزار: خروجی حساس (مثلاً متن ایمیل) قبل از ارسال برای انسان نمایش داده میشود.
- تکمیل اطلاعات ناقص: وقتی دادهای (مثل شناسهٔ سفارش) در مکالمه نیست، از انسان پرسیده میشود و پاسخ وارد state میشود.
معماری توقف و ازسرگیری در LangGraph چطور کار میکند؟
LangGraph اجرا را در واحدهایی به نام superstep پیش میبرد و در پایان هر واحد، وضعیت را در چکپوینتر مینویسد. وقتی نودی interrupt() صدا میزند، runtime اجرای همان نود را با پرتاب GraphInterrupt متوقف میکند، payload شما را همراه وضعیت در چکپوینتر ثبت میکند و invoke یا stream را با کلید __interrupt__ در خروجی برمیگرداند. هیچ پردازش پسزمینهای منتظر نمیماند؛ صبر، مسئولیت کلاینت شماست.
- 1
اجرای عادی تا نقطهٔ تصمیم
گراف با thread_id اجرا میشود و نودها به ترتیب اجرا میشوند؛ وضعیت در هر superstep در چکپوینتر ذخیره میشود.
- 2
برخورد با interrupt و توقف
نود تأیید interrupt(payload) را صدا میزند؛ اجرای نود متوقف و payload همراه وضعیت ثبت میشود.
- 3
دریافت payload در کلاینت
خروجی invoke حاوی کلید __interrupt__ است؛ سؤال را به UI میبرید و thread_id و شناسهٔ interrupt را نگه میدارید.
- 4
دریافت تصمیم انسان
اپراتور در UI تأیید/رد میزند یا مقداری را ویرایش میکند؛ تصمیم میتواند bool، رشته یا شیء JSON باشد.
- 5
ازسرگیری با Command
همان config با thread_id قبلی را استفاده کنید و Command(resume=...) بفرستید؛ مقدار resume به خروجی interrupt برمیگردد و نود از ابتدا اجرا میشود.
| جزء | نقش | مثال | بدون آن چه میشود؟ |
|---|---|---|---|
| interrupt() | توقف داینامیک نود با payload دلخواه | interrupt({"question": ...}) | هیچ نقطهٔ کنترل انسانی ندارید |
| Command(resume=...) | ازسرگیری با مقدار تصمیم انسان | Command(resume=True) | اجرای متوقف قابل ادامه نیست |
| checkpointer | ذخیرهٔ وضعیت بین دو فراخوانی | InMemorySaver / PostgresSaver | interrupt خطا میدهد |
| thread_id | تفکیک وضعیت هر مکالمه | "thread_id": "ticket-101" | وضعیتها قاطی میشوند |
| payload | زمینهای که انسان برای تصمیم میبیند | نام ابزار و آرگومانها | اپراتور کورکورانه تأیید میکند |
پیشنیازها: آمادهسازی محیط و کلید API برای اتصال به APX24
- Python 3.10 یا جدیدتر را نصب کنید (برای نسخهٔ TypeScript: Node.js 18+).
- با pip بستهٔ langgraph نسخهٔ 1.x را نصب کنید.
- در پنل APX24 یک کلید API بسازید و مطمئن شوید اعتبار حساب شما فعال است.
- کلید را در متغیر محیطی APX24_API_KEY نگه دارید — هرگز در کد هاردکد نکنید.
- با یک curl ساده اتصال به endpoint را تست کنید تا بعداً خطاهای شبکه را با خطاهای منطقی گراف اشتباه نگیرید.
گام ۱ و ۲ — چطور نود تأیید انسانی را با interrupt() بسازیم و تا نقطهٔ توقف اجرا کنیم؟
گراف نمونه ما سه نود دارد: call_model که در پروژهٔ واقعی درخواست را به APX24 میفرستد و tool_call میگیرد، human_approval که گیت انسانی است، و run_tool که فقط با تأیید اجرا میشود. برای تمرکز بر HITL، خروجی مدل را شبیهسازی کردهایم؛ ساختار کد عیناً همان چیزی است که با یک فراخوانی واقعی chat/completions به دست میآورید.
پشت صحنه چه اتفاقی میافتد؟ نود call_model شما (یا SDK ایجنت) یک درخواست به APX24 میفرستد و مدل — مطابق قالب OpenAI — درخواست فراخوانی ابزار را در فیلد tool_calls برمیگرداند. دو بلاک بعدی همان رفت و برگشت HTTP را در سطح خام نشان میدهد تا ببینید دقیقاً چه چیزی قرار است از گیت انسانی رد شود.
گام ۳ — چطور اجرا را با Command(resume=...) ازسر بگیریم و نتیجه را ببینیم؟
وقتی اپراتور در UI دکمهٔ تأیید یا رد را زد، سرور شما یک درخواست جدید به همان گراف با همان thread_id میفرستد، اما اینبار بهجای ورودی اولیه، Command(resume=...) میدهد. مقدار resume میتواند bool، رشته یا شیء JSON باشد و دقیقاً همان چیزی است که تابع interrupt در نود برمیگرداند؛ از این نقطه به بعد، منطق الگو در دست خود شماست.
سه اشتباه رایج که ایجنت تأییدمحور شما را زمین میزند
چطور همین ایجنت را در JavaScript و TypeScript بسازیم؟
اگر بکاند شما Node است، خبر خوب این است که LangGraph.js دقیقاً همین معناشناسی را با همان نامها ارائه میدهد: interrupt از همان بسته، و Command بهصورت کلاس با new. تعریف state بهجای TypedDict با Annotation انجام میشود و compile هم checkpointer را در همان آبجکت options میگیرد. بقیهٔ منطق — شرط تأیید، رد، ویرایش — یکبهیک ترجمه میشود.
interrupt() یا interrupt_before؟ کدام روش توقف را انتخاب کنیم؟
| ویژگی | interrupt() داینامیک | interrupt_before ایستا |
|---|---|---|
| ارسال payload به کلاینت | دارد — هر مقدار JSON | ندارد |
| توقف شرطی (فقط موارد پرریسک) | دارد — داخل منطق نود | ندارد — همیشه توقف |
| دریافت تصمیم انسان در نود | با Command(resume=...) | با update_state دستی |
| مکان تعریف | داخل بدنهٔ نود | هنگام compile |
| کاربرد اصلی | تأیید انسانی، ویرایش، تکمیل داده | دیباگ، خطگیری، آزمایش |
| وضعیت در 1.x | الگوی توصیهشده | پشتیبانی میشود؛ برای HITL نیست |
انتخاب مدل و محاسبهٔ هزینه: ایجنت تأییدمحور روی APX24 چقدر هزینه دارد؟
دو مثال حلشدهٔ کامل: تأیید/رد ارسال ایمیل و ویرایش آرگومانها
تمرینهای کدی: یادگیری را تثبیت کنید
خواندن الگو کافی نیست؛ چهار تمرین زیر را واقعاً اجرا کنید. تمرین ۱ و ۲ را روی همان گراف نمونهٔ مقاله انجام دهید و تمرین ۳ و ۴ را روی کپی خودتان. برای هر تمرین، خروجی مورد انتظار مشخص است تا نتیجه را خودتان verify کنید.
- P1 (ساده): گراف نمونه را اجرا کنید، payload را چاپ کنید و دو بار رزومه بزنید (True و False) — خروجی هر دو مسیر را با بخش ۵ مقایسه کنید.
- P2 (متوسط): تابع is_risky اضافه کنید تا فقط ابزارهای refund_customer و delete_record توقف بخورند و بقیه بیوقفه اجرا شوند.
- P3 (متوسط): الگوی سهاکشن (approve/edit/reject) را روی ابزار refund_customer پیاده و خروجی final["tool_call"]["args"] را verify کنید.
- P4 (چالشی): در یک نود دو interrupt پشتسرهم بزنید (تأیید مبلغ، سپس تأیید متن پیام) و با یک رزومهٔ mapمحور بر اساس شناسهٔ interrupt هر دو را پاسخ دهید.




