یک فراخوانی API با هزینه ۰.۰۰۱ دلار که ۱۰ بار تکرار شود، گرانتر از یک فراخوانی ۰.۰۵ دلاری است که تکلیف را یکباره حل میکند. این تلهٔ اقتصادی، هستهٔ اصلی مشکلی است که ai-loopguard برای حل آن ساخته شده است؛ یک مدارشکن (Circuit Breaker) متنباز که در ۱۱ ژوئیه ۲۰۲۶ منتشر شد تا مانع از سقوط عاملهای هوش مصنوعی در چرخههای شکست بینهایت شود. این کتابخانه در گیتهاب به آدرس github.com/deghosal-2026/ai-loopguard در دسترس است و میتوان آن را با دستور pip install ai-loopguard تحت مجوز MIT نصب کرد.
عاملهای خودمختار اغلب زمانی دچار «حالات توقف» (Stuck States) میشوند که مدلهای غیرقطعی (Non-deterministic) با محیطهای قطعی (Deterministic) مانند پایگاههای کد یا APIها تعامل میکنند. تصور کنید ساعت ۲ بامداد با یک هشدار مواجه شوید و ببینید یک خط لولهٔ عاملمحور، برای وظیفهای ۲ دقیقهای، ۶ ساعت در حال اجراست. بررسی لاگها نشان میدهد مدل در ۵۰۰ تکرار، کد را تغییر داده، در تست شکست خورده، تغییرات را بازگردانده و دوباره شکست خورده است. در چنین حالتی، صورتحساب API برای یک وظیفهٔ شکستخورده به ۲۰۰ دلار میرسد. طبق گزارش توسعهدهندگان، اگرچه کتابخانههای بازسنجی (Retry) وجود دارند — همانطور که در تحلیل قبلی ما دربارهی کتابخانه بدون وابستگی Backon اشاره کردیم — اما اکثر ابزارهای موجود صرفاً همان اقدام شکستخورده را تکرار میکنند. آنها فاقد هوشمندی لازم برای تشخیص «نوسان» (Oscillation) هستند و همین موضوع منجر به تورم عظیم صورتحسابها و مسدود شدن خطوط استقرار (Deployment Pipelines) میشود. این چالشهای تکرارپذیری یادآور تلاشهای اخیر برای مدیریت توهمات کدنویسی در محیطهای پیچیده است تا از ورود عاملها به حلقههای مرگبار جلوگیری شود.
ai-loopguard خود را با قرار گرفتن بهعنوان یک لایهٔ کیفی بین چارچوبهای عامل (Agent Frameworks) و ردیابهای هزینه متمایز میکند. بر اساس مستندات این پروژه در dev.to، این ابزار جایگزین پشتهٔ عامل نمیشود، بلکه منطق موجود را تنها با چهار خط کد در بر میگیرد. این کتابخانه خلأ «میانهای گمشده» را پر میکند؛ جایی که چارچوبهایی مثل LangGraph یا CrewAI هیچ مکانیزم تشخیص شکستی ندارند و ابزارهای مشاهدهپذیری مثل LangSmith یا LangFuse تنها داشبوردهای پسرویدادی (After-the-fact) ارائه میدهند و حلقهٔ کنترلی ندارند. ابزارهای دیگری مانند agentcost-sdk یا compute-cfo هزینههای هر فراخوانی را ردیابی میکنند، اما قادر به تشخیص حلقههای توقف یا فعالسازی ارتقای مدل نیستند. حتی چارچوبهای جامعی مثل Overseer نیازمند جایگزینی کل پشته هستند، در حالی که loopguard یک کتابخانه Drop-in است که به راحتی اضافه میشود.
مکانیسمهای تشخیص فراتر از شمارندههای ساده
این کتابخانه از شمارندههای ساده و سادهلوحانه تکرار (مانند max_iterations=10) که نمیتوانند تفاوت میان یک «وظیفه سخت که نیاز به پیشرفت دارد» و یک «حلقه دایرهای» را بفهمند، فاصله گرفته است. به جای آن، چهار نوع محرک قطعی (Deterministic Trigger) را به کار میگیرد که با یک ترتیب اولویت ثابت اجرا میشوند: custom $\rightarrow$ repeated_error $\rightarrow$ test_failure $\rightarrow$ schema_invalid. این ترتیب ثابت تضمین میکند که تغییرات در پیکربندی نتواند بهطور تصادفی ترتیب محرکها را تغییر دهد.
- خوشهبندی خطاها (Error Clustering): شناسایی تکرار یک نوع استثنا (Exception) و پیام خطا در N گام متوالی. این مکانیسم الگوهایی مانند
ValueError: rate limitedکه ۳ بار تکرار شده را شناسایی میکند و سیگنال میدهد که عامل از خطا درس نمیگیرد. - چرخههای شکست در تست (Test-Failure Cycles): شناسایی عاملهایی که یک تست را اصلاح میکنند اما تست دیگری را میشکنند و در یک نوسان «پاس-فیل-پاس» میافتند. این ابزار بهطور خاص نظارت میکند که آیا یک تست خاص N بار متوالی شکست میخورد یا وضعیت آن نوسان دارد. برای مثال، حالتی را میگیرد که عامل در تلاش برای اصلاح
test_lintباعث شکستtest_parserمیشود. - شکست در اعتبارسنجی طرحواره (Schema Validation Failures): تشخیص زمانی که یک عامل با وجود اصلاحات مکرر، بهطور مداوم JSONهای بدشکل برمیگرداند (مثلاً عدم رعایت قرارداد
{"answer": str, "citations": list}). - کالبکهای سفارشی (Custom Callbacks): اجازه میدهد توسعهدهندگان اکتشافات دامنه-محور (Domain-specific heuristics)، محدودیتهای زمانی واقعی (Wall-clock timeouts) یا تجاوز از بودجه توکن را تعریف کنند. هرگاه کالبک مقدار
Trueبرگرداند، محرک فوراً فعال میشود.
لایهٔ تصاعدی (Escalation)
وقتی یک حلقه شناسایی میشود، ai-loopguard سیستم را متوقف یا کرش نمیکند. این ابزار از یک لایه تصاعدی برای حل بنبست از طریق سه حالت اصلی استفاده میکند:
۱. ارتقای مدل (Model Upgrade): کتابخانه بافتار شکست — شامل آنچه امتحان شد، آنچه شکست خورد و ردهای خطا (Error Traces) — را بستهبندی میکند. این دادهها پاکسازی شده و به یک مدل «پیشرو» (Frontier) قویتر مانند GPT-4o ارسال میشوند تا راه خروج از تله را استدلال کند. یک ساختار رایج، جفت کردن یک مدل ارزانقیمت مانند qwen2.5-coder با یک مدل ارتقایی با استدلال بالا است.
۲. انسان در حلقه (Human-in-the-Loop): برای جریانهای کاری حساس به هزینه، از وقفههای داخلی (Native Interrupts) در چارچوبهایی مانند LangGraph استفاده میکند. اجرای برنامه متوقف شده و از اپراتور میپرسد: «عامل در test_parser گیر کرده است (۳ شکست). آیا به GPT-4 ارتقا دهم؟ [y/n]» تا پیش از مصرف حتی یک توکن برای ارتقا، تاییدیه گرفته شود. وضعیت گراف در checkpointer ذخیره میشود تا از دست رفتن دادهها جلوگیری شود.
۳. طراحی باز-شکست (Fail-Open Design): برای تضمین قابلیت اطمینان، این مدارشکن بهگونهای طراحی شده که هرگز باعث کرش کردن عامل نشود. اگر خودِ کتابخانه با باگی در تشخیص، قطعی مدل ارتقایی یا خطای شبکه مواجه شود، سه حالت قابل پیکربندی ارائه میدهد: raise_original (پیشفرض)، return_last_output (دادههای قدیمی اما معتبر) یا return_sentinel (یک مقدار قابل تنظیم برای سیگنال دادن به شکست).
ادغام در چارچوبها و پیادهسازی
ادغام از طریق Wrapperهای تخصصی صورت میگیرد که نیاز به بازسازی حداقلی کد دارند. برای LangGraph، ابزار LangGraphHandler به چرخهٔ زندگی گرهها متصل شده و از interrupt() داخلی گراف استفاده میکند. این کار قابلیتهایی را فراهم میکند که LangGraph بهطور بومی ندارد: تشخیص حلقه توقف، تشخیص چرخه شکست تست، ارتقای خودکار و ردیابی هزینه به ازای هر وظیفه تکمیلشده.
در CrewAI، ابزار CrewAIWrapper (هدفگذاری شده برای نسخههای crewai>=0.50.0,<0.60.0) ایزولاسیون را در سطح هر عامل فراهم میکند. از آنجا که این wrapper به هر عامل یک GuardState مجزا بر اساس نقش (Role) اختصاص میدهد، اگر عامل «پژوهشگر» یک خطای بازیابی ثبت کند، باعث ارتقای نادرست برای عامل «نویسنده» که با خطای طرحواره مواجه شده است، نمیشود. این کار مانع از ایجاد الگوهای غلط در اثر ترکیب تاریخچههای مختلف عوامل (مثلاً دنبال شدن ValueError عامل A با KeyError عامل B) میگردد. تشخیصدهنده برای پیکربندی مشترک است، اما ارزیابیها مستقل هستند. این رویکرد برای جلوگیری از خطاهای زنجیرهای در شبکههای چندعاملی بسیار حیاتی است تا خرابی یک عامل باعث سقوط کل سیستم نشود.
امنیت و کاهش تهدیدات
از آنجا که مرحله ارتقا، حالات شکست عامل را به مدلهای ابری ارسال میکند، امنیت در اولویت اصلی است. این ابزار تمام خروجیهای عامل را «غیرقابل اعتماد» تلقی کرده و ۶ تهدید مشخص ذکر شده در مدل تهدید خود را کاهش میدهد:
- تزریق پرامپت (T1): استفاده از جداسازی صریح سیستم در مقابل کاربر و قرار دادن جداکنندهها (Delimiters) دور محتوای تولید شده توسط عامل برای جلوگیری از تسخیر مدل ارتقایی.
- نشت دادهها (T2): یک سیستم سانسور داخلی با استفاده از Regex و نام فیلدها، کلیدهای OpenAI، کلیدهای AWS و توکنهای گیتهاب را حذف میکند. کاربران میتوانند الگوهای سفارشی مانند
r"sk-[a-zA-Z0-9]{48}"یا فیلدهای خاصی مثلapi_keyوssnرا اضافه کنند. - تخلیه منابع (T3): یک سقف سخت
max_history_steps(پیشفرض ۱۰۰، حداکثر ۱۰۰۰) برای جلوگیری از اشباع حافظه توسط تاریخچههای نامحدود. - حمله DoS اقتصادی (T6): برای جلوگیری از هزینههای سرسامآور در صورت وجود باگ در حلقه، سقف
max_escalations_per_run(پیشفرض ۱، حداکثر ۱۰) تعداد فراخوانیهای گرانقیمت در هر اجرا را محدود میکند. - در دسترس بودن مدل (T4): حالتهای Fail-open تضمین میکنند که شکست مدل ارتقایی باعث مرگ کل سیستم نشود.
- زنجیره تأمین (T5): از طریق وابستگیهای پینشده (Pinned Dependencies) و اجرای
pip-auditدر CI کاهش مییابد.
بافتار (Context) همچنین از طریق فشردهسازی محافظت میشود. به جای ارسال کامل تاریخچه، تنها گام اول، آخرین گام و خلاصهای از مراحل ارسال میشود که توسط max_context_tokens (پیشفرض ۴۰۰۰) محدود شده است.
مطالعه میدانی و عملکرد
در یک مطالعه میدانی روی ۱۵ وظیفه در سه مخزن بزرگ — SWE-agent (حدود ۱۴ هزار ستاره)، Aider (حدود ۴۶ هزار ستاره) و LangGraph (حدود ۱۰۰ هزار ستاره) — این کتابخانه به نرخ موفقیت ۱۰۰٪ (۱۵ از ۱۵) رسید، در حالی که نرخ موفقیت بدون این گارد صفر بود (۰ از ۱۵). این نتایج در راستای متدهای مهندسی آشوب برای شناسایی نقاط شکست است که با فشار آوردن به سیستم، نقاط ضعف عاملها را پیش از محیط عملیاتی آشکار میکند.
نتایج تفکیکی به شرح زیر بود:
- SWE-agent: ۵ از ۵ وظیفه موفق شدند (محرکها: شکست تست، خطای تکراری، طرحواره نامعتبر، نوسان).
- Aider: ۵ از ۵ وظیفه موفق شدند (محرکها: شکست تست، خطای تکراری، طرحواره نامعتبر، نوسان).
- LangGraph: ۵ از ۵ وظیفه موفق شدند (محرکها: خطای تکراری، طرحواره نامعتبر، تایماوت سفارشی، شکست تست).
این مطالعه گزارش داد که زمان کل اجرا ۵۰٪ کاهش یافت (از ۹۲۳ میلیثانیه به ۴۵۸ میلیثانیه) و هر ارتقا منجر به یک نتیجه معتبر شد.
سربار فنی (Technical Overhead) تقریباً نامرئی است. بنچمارکها نشان میدهند هزینه تشخیص تنها ۲.۷۵ میکروثانیه است — کمتر از یک خطای پیشبینی شاخه (Branch Misprediction) در CPU. سایر معیارهای عملکردی عبارتند از:
- بستهبندی بافتار: ۱۰.۲۵ میکروثانیه
- نرخ عبور سانسور (Redaction): ۰.۸۷ میلیثانیه
- نرخ عبور پاکسازی (Sanitization): ۲۱.۶ میکروثانیه
- ردپای حافظه: ۳۹.۹ کیلوبایت
- زمان وارد کردن (Import Time): ۵۴.۸ میلیثانیه
- جریان کامل ارتقا: ۲.۶ میکروثانیه
پروژه با استانداردهای کیفی سختگیرانه شامل ۴۳۶ تست، پوشش کد ۹۷.۳٪ و عدم وجود هیچ خطایی از Ruff یا Mypy (در حالت سختگیرانه) نگهداری میشود. مجموعه تستها شامل تستهای واحد، یکپارچهسازی، end-to-end و مطالعات میدانی است و در CI از LLMهای شبیهسازی شده (Mock) برای جلوگیری از هزینههای API استفاده میکند. برای فرمتهای لاگ JSONL نیز از تست اسنپشات استفاده شده است.
اثر مهندسی و مشاهدهپذیری
این تغییر، نحوه اندازهگیری کارایی عاملها توسط مهندسان را دگرگون میکند. به جای ردیابی «هزینه هر فراخوانی»، ai-loopguard معیار «هزینه هر وظیفه تکمیل شده» را معرفی میکند که ترکیبی از تکرارها، حلقههای شکست و هزینههای ارتقا است. همچنین «نرخ ارتقا» (تعداد ارتقاها/کل فراخوانیها) را ردیابی میکند تا مشخص شود آیا سیستم صرفاً یک مسیریاب (Router) در لباس عامل است (جایی که بیش از ۸۰٪ درخواستها ارتقا مییابند). این ابزار بین «مسیریابی» (مدل نتوانست انجام دهد) و «جایگزینی شکست» (مدل در دسترس نبود) تفاوت قائل میشود.
برای تیمهایی که عاملها را در خطوط CI/CD اجرا میکنند (مانند بررسی خودکار PRها یا تولید کد)، این ابزار مانع از توقف عاملها و مسدود شدن کل خط استقرار میشود. مشاهدهپذیری از طریق لاگهای ساختاریافته JSONL و بازههای OpenTelemetry (OTel) با استفاده از OTelEventHook ادغام شده است. کاربران میتوانند دستور loopguard analyze logs.jsonl --summary را اجرا کنند تا تفکیک هزینهها بر اساس نوع محرک (مثلاً repeated_error در مقابل test_failure) را مشاهده کنند.
معماری و دقت مهندسی
این کتابخانه با ۱۸ ماژول ساخته شده و عمدتاً به langchain-core و pydantic وابسته است. پروژه توسط یک مجموعه مستندات گسترده پشتیبانی میشود، شامل یک PRD با ۸۸۶ خط (پوشش اهداف و مدلهای تهدید)، یک SPEC با ۱,۵۱۱ خط (جزئیات خط لوله ارتقا) و یک WBS با ۱,۲۴۷ خط (پوشش ۱۲ سنگبنای تکمیل شده).
مدل GuardConfig تضمین میکند که تمام فیلدها توسط Pydantic محدود شدهاند و لاگهای EscalationEvent تصویر جنایی (Forensic) کاملی شامل وضعیت sanitized، فیلدهای حذف شده (redacted_fields) و دستهبندی ارتقا را ارائه میدهند.
نقشه راه آینده
آنچه باید دید این است که جامعه توسعهدهندگان چگونه کتابخانه محرکها را گسترش میدهند. نقشه راه نسخه v0.2.0 شامل موارد زیر است:
- تشخیص چرخه توهم (Hallucination Cycle): شناسایی زمانی که عامل ادعا میکند باگی را اصلاح کرده که پیشتر برای حل آن تلاش کرده و شکست خورده است.
- امنیت پیشرفته: یک تشخیصدهنده کامل تزریق پرامپت.
- هماهنگی: هماهنگی بین چندین عامل و پیکربندی از طریق YAML یا Env.
نسخه v0.3.0 قصد دارد یک SDK برای محرکهای سفارشی و یک موتور سیاست ارتقای آگاه-از-هزینه (Cost-aware) معرفی کند. اهداف پس از عرضه شامل یک داشبورد وب و ادغام با LangSmith است.
گام بعدی شما
- اگر از LangGraph استفاده میکنید،
LangGraphHandlerرا برای جلوگیری از اتلاف بودجه در حلقههای تکراری تست کنید. - در تنظیمات
GuardConfigبرای توکنهای حساس سازمان خود، الگوهای Regex سفارشی تعریف کنید تا از نشت دادهها در مرحله ارتقا جلوگیری شود. - نرخ ارتقا (Escalation Rate) را در لاگهای JSONL بررسی کنید تا بفهمید کدام بخش از جریان عامل شما بیش از حد به مدلهای گرانقیمت وابسته است.
اما داستان سختافزاری این تحول حتی شگفتانگیزتر است — به تحلیل ما دربارهی تراشههای Blackwell مراجعه کنید.
گفتگو