بسیاری از آموزش‌ها اجزای یک سیستم ایجنتی را جداگانه بررسی می‌کنند: یک ساندباکس ساده در خلأ، یک بستر تست بدون ناظر، یا تنظیم ترکینگ بدون گیت‌های امنیتی. اما چالش اصلی مهندسی زمانی رخ می‌دهد که این لایه‌ها را کنار هم قرار می‌دهید؛ جایی که ناسازگاری سهمیه توکن‌ها، بلاک‌های ناخواسته در گیت‌های امنیتی و ناهماهنگی متریک‌ها سیستم را فلج می‌کنند.
در این درس پایانی، تمام بخش‌های ساخته‌شده شامل زنجیره گیت، محیط ایزوله ساندباکس، بستر ارزیابی و تلمتری OTel را در یک حلقه اجرایی واحد ادغام می‌کنیم تا یک باگ پایتونی واقعی را رفع کند. با جایگزینی مدل زبانی با یک خطمشی قطعی مبتنی بر ماشین وضعیت، ساختار معماری را بدون نیاز به کلیدهای API خارجی یا اجرای ابری پرهزینه، به‌صورت کاملاً محلی، سریع و تکرارپذیر روی سیستم شخصی پیاده‌سازی می‌کنید.
ثمره‌ی تلاش‌های مسیر A اینجاست. در این درس، زنجیره‌ی گیت، ساندباکس، بستر آزمایشی ارزیابی و اسپن‌های OTel را به هم پیوند می‌زنیم تا یک ایجنت کدنویسی کاربردی بسازیم؛ ایجنتی که یک باگ واقعی (در مقیاس فیکسچر و کوچک) را در پروژه‌ای چندفایلی در Python برطرف میکند. این ایجنت بهجای LLM، از یک خطمشی قطعی (Deterministic policy) استفاده میکند؛ این جایگزینی باعث می‌شود درس کاملاً تکرارپذیر باشد و نشان می‌دهد که بخش جذاب ماجرا از همان ابتدا بستر آزمایشی بوده است. قرارداد کاری دقیقاً یکسان است: یک مدل واقعی درست در درز و مرز اتصال خطمشی می‌نشیند.
اهداف یادگیری
- ترکیب زنجیره‌ی گیت، ساندباکس، بستر آزمایشی ارزیابی و سازنده‌ی اسپن در یک حلقه‌ی ایجنت واحد.
- پیاده‌سازی یک خطمشی قطعی که با استفاده از
read_file،run_testsوwrite_fileباگ یک فیکسچر را رفع میکند. - اعمال سهمیه‌ی گام‌های سراسری به همراه سهمیه‌ی توکن مشاهده در طول یک اجرای سرتاسری.
- انتشار ردگیری محاسبات کامل OTel GenAI و معیارهای Prometheus برای کل فرایند اجرا.
- اعتبارسنجی اینکه ایجنت فیکسچر را در کمتر از 12 گام و بدون هیچ فعال‌شدن ناخواسته‌ی گیت روی ابزارهای مجاز حل میکند.
صورت مسئله
بیشتر دموهای ایجنت به‌صورت ایزوله کار می‌کنند: ساندباکس به‌تنهایی، بستر آزمایشی ارزیابی به‌تنهایی، و ارسال‌کننده‌ی اسپن هم به‌تنهایی. کارشان در ظاهر خوب به نظر می‌رسد؛ اما وقتی آن‌ها را ترکیب می‌کنید، درزها و آرتیفکت‌های مرزی خود را نشان می‌دهند.
زنجیره‌ی گیت وضعیت ALLOW را برمی‌گرداند، اما ساندباکس به دلیلی که زنجیره پیش‌بینی نکرده بود از اجرا سر باز می‌زند. بستر آزمایشی ارزیابی موفقیت را ثبت میکند، اما اسپن‌های OTel می‌گویند گیت جلوی اجرای ابزاری را گرفته که ایجنت ادعای استفاده از آن را دارد. شمارنده‌ی Prometheus دو بار افزایش می‌یابد، در حالی که باید یک بار شمرده می‌شد. سهمیه‌ی توکن مشاهده تمام می‌شود، اما ایجنت به کارش ادامه می‌دهد؛ چون بودجه داخل زنجیره ردگیری می‌شد و ساندباکس از آن بی‌خبر بود.
این درس، آزمون یکپارچگی کل این مسیر آموزشی است. ایجنت باید شش کار را به ترتیب انجام دهد: پروژه را بخواند، تست‌ها را اجرا کند، باگ را از روی خطای تست شناسایی کند، اصلاحیه را بنویسد، تست‌ها را دوباره اجرا کند و متوقف شود. تک‌تک عملیات‌ها از زنجیره‌ی گیت عبور می‌کنند. همه‌ی فراخوانی‌های ابزار داخل ساندباکس اجرا می‌شوند. هر گام در قالب یک اسپن پوشش داده می‌شود. در پایان، بستر آزمایشی ارزیابی به کل فرایند امتیاز می‌دهد.
مفهوم اصلی
خطمشی ایجنت یک ماشین وضعیت با پنج وضعیت است:
SURVEY: ایجنت فهرست فایل‌های پروژه را می‌خواند. وضعیت بعدی RUN_TESTS است.
RUN_TESTS: ایجنت دستور تست را اجرا میکند. اگر تست‌ها پاس شوند، ماشین وضعیت با موفقیت متوقف می‌شود؛ در غیر این صورت وضعیت بعدی INSPECT است.
INSPECT: ایجنت فایل سورس دارای خطا را می‌خواند. وضعیت بعدی FIX است.
FIX: ایجنت فایل اصلاح‌شده را می‌نویسد. وضعیت بعدی VERIFY است.
VERIFY: ایجنت دوباره دستور تست را اجرا میکند. اگر تست‌ها پاس شوند، با موفقیت متوقف می‌شود؛ در غیر این صورت با وضعیت شکست متوقف خواهد شد.
هر وضعیت متناظر با یک فراخوانی ابزار است. هر فراخوانی ابزار از زنجیره‌ی گیت عبور میکند. اگر فراخوانی ابزاری رد شود، ایجنت امتناع مدل را در ردگیری محاسبات ثبت کرده و متوقف می‌شود.
باگ فیکسچر، یک خطای یکی‌کم‌و‌زیاد (off-by-one) در fizz.py است. خطمشی قطعی با استفاده از regex باگ را از پیام خطای تست تشخیص می‌دهد و فایل اصلاح‌شده را تولید میکند. جایگزینی این خطمشی با یک LLM، قرارداد بستر آزمایشی را تغییر نمی‌دهد.
معماری
این درس کاملاً خودکفاست. هر جزء سازنده‌ی پیشین در مقیاسی حداقلی درون main.py بازنویسی شده است (گیت، ساندباکس، دفتر کل و اسپن) تا درس بدون نیاز به ایمپورت از درس‌های هم‌جوار اجرا شود. نام‌ها دقیقاً با درس‌های 25 تا 28 مطابقت دارند تا نگاشت مفهومی کاملاً روشن و بدون ابهام بماند.
آنچه خواهید ساخت
آنچه در main.py ارائه می‌شود:
- اجزای سازنده‌ی حداقلی بستر آزمایشی، با همان نام‌های درس‌های 25 تا 28:
GateChain،Sandbox،ObservationLedger،SpanBuilderوMetricsRegistry. - کلاس
CodingAgentPolicy: ماشین وضعیت با پنج وضعیت. - هلپر
Repo: آماده‌سازی یک دایرکتوری موقت با فیکسچر باگ‌دارِ همراه پروژه. - کلاس
AgentRun: هدایت خطمشی، ارسال فراخوانی‌ها از طریق بستر آزمایشی و بازگرداندنAgentRunReport. - یک فیکسچر همراه (
fixture_repo/) شامل src/fizz.py، tests/test_fizz.py و ساختار درختی expected/ برای بستر آزمایشی ارزیابی. - دمو: اجرای سرتاسری خطمشی، چاپ گام‌به‌گام ردگیری محاسبات، اعتبارسنجی پاس شدن تست‌ها (assert pass) و چاپ معیارها.
فیکسچر همراه پروژه ساختاری مشابه وظیفه‌ی درس 27 دارد: یک فایل باگ‌دار و یک فایل تست. پیام خطای تست داده‌های کافی را در اختیار خطمشی قطعی قرار می‌دهد تا اصلاحیه را تشخیص دهد. یک LLM واقعی نیز همین کار را با سرعتی کمتر و بازخوانی گسترده‌تر انجام می‌دهد، اما تاثیری روی انتظارات بستر آزمایشی نخواهد داشت.
چرا خطمشی یک LLM نیست؟
یک LLM واقعی به کلید API، فراخوانی شبکه و رفتار تصادفی غیرقابل‌تایید نیاز دارد. این در حالی است که بخش مهم این درس، همان بستر آزمایشی است. جایگزینی آن با یک خطمشی قطعی اجازه می‌دهد این درس روی لپ‌تاپ هر توسعه‌دهنده‌ای بدون وابستگی خارجی اجرا شود و مجموعه تست‌ها بتوانند تعداد دقیق گامها را بسنجند.
خطمشی این درس زیرمجموعه‌ی دقیقی از کارهایی است که یک ایجنت LLM انجام می‌دهد. خطمشی مخزن را می‌خواند، تست ناموفق را می‌بیند، خط مشکل‌دار را پیدا میکند و اصلاحیه را می‌فرستد. یک LLM دقیقاً همین حلقه را با همان قرارداد بستر آزمایشی طی میکند؛ ثبت داده‌ها در پشت صحنه کاملاً یکسان است.
اعتبارسنجی‌های دمو
دموی سرتاسری در زمان خروج پنج مورد را بررسی میکند و مجموعه‌ی تست‌ها نیز دوباره آن‌ها را به‌شکل برنامه‌نویسی‌شده اعتبارسنجی می‌کنند:
خطمشی توانسته است فیکسچر را در کمتر از 12 گام حل کند.
سهمیه‌ی توکن مشاهده در هیچ نقطه‌ای رد نشده است.
هیچ امتناعی در گیت برای ابزارهای مجاز رخ نداده است (ایجنت هیچ ابزار نامجازی از خود نساخته است).
هر گام یک اسپن متناظر در traces.jsonl دارد.
خروجی Prometheus شامل یک ورودی tools_called_total{tool="read_file"} و یک هیستوگرام tool_latency_ms است.
هماهنگی با بقیه‌ی مسیر A
این درس نقطه‌ی یکپارچه‌سازی است. در درس 25 زنجیره‌ی گیت را نوشتیم. در درس 26 ساندباکس را آماده کردیم. در درس 27 بستر آزمایشی ارزیابی را توسعه دادیم. در درس 28 قابلیت مشاهده‌پذیری را پیاده کردیم. اکنون درس 29 اثبات میکند که این بخش‌ها در قالب یک سیستم کار می‌کنند. ارتقای بستر آزمایشی ایجنت به یک محیط واقعی آسان است: خطمشی قطعی را با یک مدل جایگزین کنید، فیکسچر پروژه را با وظیفه‌ای از یک مخزن واقعی تغییر دهید و صادرکننده‌ی JSONL را به OTLP متصل کنید.
اجرای کد
cd phases/19-capstone-projects/29-end-to-end-coding-task-demo
python3 code/main.py
python3 -m pytest code/tests/ -vدمو ردگیری محاسبات گام‌به‌گام، گزارش نهایی ارزیابی و خروجی Prometheus را نمایش می‌دهد. کد خروج صفر است. تست‌ها انتقال وضعیت‌های خطمشی، امتناع‌های گیت در فراخوانی‌های ساختگی ابزار، اجرای سرتاسری روی فیکسچر همراه، و پایدار بودن سهمیه‌ی گامها را پوشش می‌دهند.