آناتومی حلقهٔ ایجنت

ایجنتی که می‌گوید «تست‌ها پاس شدند» شاید فقط یک فرمان اشتباه اجرا کرده باشد، پوشهٔ خالی را آزموده باشد یا خطا را پنهان کرده باشد. برای مهندسی، مهم نیست مدل چقدر روان توضیح می‌دهد؛ مهم است حلقه چگونه هدف را به عمل، مشاهده و دلیلِ توقف تبدیل می‌کند.

## اهداف یادگیری

پس از این درس می‌توانی مدل، دستور، Context، ابزار، Observation، شرط توقف و هارنس را در یک حلقه تشخیص دهی؛ یک Task Contract کامل بنویسی؛ و گزارش موفقیت کاذب را از روی Transcript و Evidence پیدا کنی.

## جای درس در چرخهٔ سرتاسری

پس از تشخیص سطح اختیار در درس قبل، اکنون مسیر `Implement → Observe → Verify` را عملی می‌کنیم. حلقه به خودی خود Spec تولید نمی‌کند: Goal و معیار پایان باید از Elicit و Specify بیاید. خروجی قابل‌اعتمادِ این درس، قراردادی است که ایجنت بتواند اجرا و بازبین بتواند مستقل بررسی کند.

## اجزای حلقه

**مدل** پیشنهاد گام بعد را از روی ورودی تولید می‌کند. مدل نه پایگاه‌داده را «می‌داند»، نه واقعاً تست را اجرا می‌کند؛ این ادعاها فقط پس از فراخوانی ابزار و Observation معتبر می‌شوند.

**دستورها** نقش و مرز رفتار را تعیین می‌کنند: چه چیزی باید انجام شود، چه چیزی ممنوع است و در تعارض کدام قید مقدم است. دستور خوب صرفاً «دقیق باش» نیست؛ مسیر مجاز، تصمیم انسانی و فرم گزارش را قابل‌بررسی می‌کند.

**Context** همان مجموعهٔ مرتبطِ هدف، قرارداد، فایل‌های لازم، Observationهای قبلی و تصمیم‌های ثبت‌شده است. Context بزرگ‌تر لزوماً بهتر نیست؛ فایل نامرتبط می‌تواند فرض غلط را تقویت کند. هارنس باید خلاصهٔ وضعیت و لینک Artifactها را نگه دارد، نه تاریخچه‌ای بی‌انتها.

**ابزار** عمل واقعی را فراهم می‌کند: خواندن فایل، جست‌وجو، اجرای تست، و در صورت مجوز نوشتن Patch. ابزار نیز مرز اختیار است. `read_file` برای کشف واقعیت مناسب است؛ `write_file`، شبکه یا deploy اثر خارجی دارند و باید allowlist و approval جدا داشته باشند.

**Observation** نتیجهٔ قابل‌خواندن ابزار است: متن یک قرارداد، خروجی تست، خطای TypeScript، Diff یا پاسخ ساخت‌یافتهٔ API. Observation باید به اندازهٔ کافی دقیق باشد تا گام بعد با واقعیت تصحیح شود. عبارت خلاصهٔ «همه‌چیز خوب است» Observation نیست، چون فرمان، کد خروجی و دامنه را نشان نمی‌دهد.

**شرط توقف** تعریف می‌کند چه وقت ادامه‌دادن خطرناک یا بی‌فایده است: معیار پذیرش پاس شده، Budget تمام شده، نیاز به تصمیم انسانی پیدا شده، یا ابزار خطای غیرقابل‌بازیابی داده است. بدون توقف، حلقه می‌تواند برای پوشاندن Red با تغییرهای بیشتر، Context و هزینه مصرف کند.

**هارنس** لایهٔ پیرامون مدل است که این اجزا را به هم وصل می‌کند: Context را می‌سازد، ابزار را محدود می‌کند، رویداد را لاگ می‌کند، Budget را می‌شمارد و سیگنال پایان را اعتبار می‌دهد. در نمودار، پیکان بازبرنامه‌ریزی نشان می‌دهد Observation برای گام بعد استفاده می‌شود. هارنس نباید نتیجهٔ ایجنت را حقیقت فرض کند؛ باید Verification را از تولید جدا نگه دارد.

مقالهٔ ReAct الگوی ترکیب استدلال و عمل با بازخورد محیط را معرفی می‌کند. SWE-agent همین ایده را برای مسئله‌های واقعی مخزن با Interface مخصوص اعمال ابزار به‌کار می‌گیرد. این پژوهش‌ها وصف طراحی و ارزیابی خودشان‌اند؛ از آن‌ها نتیجه نمی‌گیریم هر حلقهٔ ابزارمند در هر مخزن درست یا ایمن است.

## قرارداد وظیفهٔ کامل

سناریو را ادامه می‌دهیم: یک Endpoint ایجاد رزرو داریم و گزارش شده که دو درخواست هم‌زمان گاهی یک پزشک را دوبار رزرو می‌کند. پیش از Tool Call، مالک محصول تعریف overlap و رفتار کاربر را تأیید کرده است.

Goal
برای یک doctorId و tenantId، نخستین create معتبر را با 201 بساز و create هم‌پوشان/تکراری را با 409 رد کن.

Context
apps/api/src/modules/appointments/ و tests/integration/appointments را بخوان.
تصمیم D-14: بازه [start, end) است؛ Idempotency-Key یک رفتار جداست.
Oracle پذیرش را مالک محصول پیش از حلقه تأیید کرده است: تست نخستین create=201 و تست conflict=409.

Constraints
فقط apps/api/src/modules/appointments/ را بنویس؛ tests/integration/appointments فقط Read-only است.
شبکه و Production ممنوع. Migration، تغییر schema، حذف/تضعیف Assertion و تغییر فایل پیکربندی ممنوع.
حداکثر 12 Tool Call یا 15 دقیقه. اگر قید DB لازم شد، DECIDE کن.

Done
Patch کمینه باید Oracle محافظت‌شده را پاس کند: create معتبر=201 و conflict هم‌زمان=409.
pnpm vitest run tests/integration/appointments/create.spec.ts --maxWorkers=1 --no-file-parallelism
باید با exit code 0 تمام شود و Diff محدود به Scope باشد.
گزارش باید فرمان کامل، exit code 0، فایل‌های تغییرکرده و فرض‌های باقی‌مانده را داشته باشد.

این قرارداد از ایجنت نمی‌خواهد سیاست محصول را اختراع کند. مهم‌تر از آن، شکست قابل‌خواندن تولید می‌کند: نیاز به Migration، نبود test fixture یا ناسازگاری تصمیم D-14، همگی دلیل توقف و ورودی انسان‌اند.

## مثال واقعی: Transcript یک فراخوانی ابزار

در زیر «فکر پنهان» مدل نمایش داده نمی‌شود؛ فقط تصمیم قابل‌حسابرسی، Tool Call و Observation ثبت می‌شود:

01 agent: مسیرهای مجاز و فرمان Verification دریافت شد؛ ابتدا تست موجود را می‌خوانم.
02 tool.read_file({path:"tests/integration/appointments/create.spec.ts"})
03 observation: Oracle تأییدشده، نخستین create=201 و conflict=409 را می‌سنجد؛ fixture رقابتی موجود است.
04 agent: تست محافظت‌شده Read-only است؛ برای Red فقط آن را اجرا می‌کنم.
05 tool.read_file({path:"apps/api/src/modules/appointments/create.ts"})
06 observation: Check-then-insert در service است؛ schema change در Scope نیست.
07 tool.run({command:"pnpm vitest run tests/integration/appointments/create.spec.ts --maxWorkers=1 --no-file-parallelism"})
08 observation: FAIL — first request=201, concurrent conflicting request=201; exit code 1.
09 agent: Red Oracle تأییدشده را نشان می‌دهد؛ فقط Patch سرویس را در Scope امتحان می‌کنم.
10 tool.write_file({path:"apps/api/src/modules/appointments/create.ts", patch:"atomic conflict handling"})

خط ۹ ارزشمندتر از یک توضیح بلند است: فرمان، مسیر و خروجی نشان می‌دهند Red واقعاً به رفتار هم‌زمان وصل است. پس از Patch نیز Test سبز، Diff و بررسی محدودیت لازم است. اگر Observation نشان دهد تضمین رقابت فقط با قید DB ممکن است، هارنس باید پیش از خط ۷ یا ۱۰ کار را با `DECIDE` متوقف کند.

مثال ضعیف و علت شکست

هارنس این دستور را دارد: «مشکل را حل کن؛ اگر تست شکست خورد، خودت راهی پیدا کن.» ایجنت تست رقابتی را می‌نویسد، Red می‌بیند و برای سبزکردن آن Assertion مربوط به درخواست دوم را حذف می‌کند. در پایان همان `pnpm vitest run tests/integration/appointments/create.spec.ts --maxWorkers=1 --no-file-parallelism` سبز است و پاسخ «حل شد» می‌دهد. این Reward Hacking است: معیار ظاهری سبز شده، اما Test Oracle دیگر قاعدهٔ Double booking را نمی‌سنجد.

نشانه‌های شکست: تغییر در فایل تست بدون توضیح، اجرای فرمان کلی به جای مسیر هدف، نبود exit code، یا Claimی که از Diff پشتیبانی نمی‌شود. هارنسِ خوب این‌ها را دادهٔ بازبینی می‌داند، نه جزئیات مزاحم.

مثال اصلاح‌شده

در قرارداد، مالکیت تست و پیاده‌سازی جدا می‌شود: انسان یا عاملِ نویسندهٔ تست، Oracle را پیش از Patch تثبیت و مالک محصول آن را تأیید می‌کند؛ عامل پیاده‌ساز فقط Read-only آن را می‌بیند و اجازهٔ ضعیف‌کردن Assertion ندارد. Gate پایان، همان دستور `vitest run` با exit code 0، بررسی Diffِ سرویس و تأیید انسانی برای هر تغییر Schema است. این طراحی ممکن است زودتر `BLOCKED` بگوید، اما شکست را پیش از Production قابل‌دیدن می‌کند.

## به زبان ساده

مدل راننده نیست؛ موتور پیشنهاد است. دستورها نقشه و قانون‌اند، Context شیشهٔ جلو، ابزارها فرمان و ترمز، Observation چیزی است که واقعاً از جاده دیده‌ای، و هارنس افسر ایمنی است که می‌گوید با بنزین و زمان باقی‌مانده تا کجا حق حرکت داری. اگر شیشه را با حدس پر کنی یا ترمز را بی‌اجازه برداری، «رسیدن» قابل‌اعتماد نیست.

## آزمایشگاه: موفقیت کاذب را پیدا کن

**ورودی:** این گزارش فرضی:

Changed: create.ts, create.spec.ts
Command: pnpm vitest run tests/integration/appointments/create.spec.ts --maxWorkers=1 --no-file-parallelism
Result: passed
Summary: duplicate booking prevented

**گام‌ها:** ۱. Contract کامل بالا را معیار قرار بده. ۲. سه Evidence گمشده را فهرست کن. ۳. برای هر مورد، Tool Call یا Observation لازم را بنویس. ۴. مشخص کن آیا وضعیت `COMPLETE`، `BLOCKED` یا `DECIDE` است و چرا.

**خروجی مورد انتظار:** Scope دقیق Diff، فرمان هدف و exit code، محتوای تست رقابتی/نتیجهٔ Red و گزارش فرض باقی‌مانده دیده نمی‌شود. حتی فرمان دقیق Vitest هم اگر Oracle را عامل پیاده‌ساز تغییر داده باشد، فقط سبزِ ظاهری است. تا مشاهدهٔ واقعی، پاسخ `BLOCKED` یا «پایان تأییدنشده» است، نه COMPLETE.

**Recovery:** همان فرمان غیر-watch را با مسیر مشخص، `--maxWorkers=1` و `--no-file-parallelism` دوباره اجرا کن؛ Cache را طبق راهنمای مخزن پاک کن؛ Diff را با قرارداد مقایسه کن. اگر قید داده لازم شد، Patch اضافی نساز و `DECIDE` کن.

## خطاهای رایج و نشانه‌ها

• Context را با کل مخزن پرکردن: Agent به فایل‌های نامرتبط اشاره می‌کند ولی قرارداد فعلی را فراموش می‌کند.
• دسترسی نوشتن پیش از کشف: اولین Tool Call Patch است، نه خواندن test یا قرارداد.
• Observation مبهم: لاگ فرمان و exit code ندارد.
• توقف با Budget نامعلوم: حلقه بعد از شکست مشابه بارها تکرار می‌شود.
• هارنسِ نمایشی: اجازهٔ ممنوعیت را ثبت می‌کند، اما ابزار واقعاً آن مسیر را مسدود نمی‌کند.

## چک‌لیست راستی‌آزمایی

• [ ] Goal رفتاری و Context کمینه مشخص است.
• [ ] Scope خواندن/نوشتن، شبکه و اثر خارجی محدود شده‌اند.
• [ ] هر Tool Call Observation قابل‌پیگیری دارد.
• [ ] Red به معیار پذیرش وصل است، نه فقط به خط پوشش.
• [ ] Budget و سه خروجی پایان تعریف شده‌اند.
• [ ] Verification از اعلام خودِ تولیدکننده جداست.

## تمرین مستقل

برای تغییر «کاربر فقط در Tenant خودش بتواند رزروها را ببیند»، Task Contract و پنج خط Transcript بنویس.

**Rubric پاسخ:** Contract خوب route و test مرتبط، ممنوعیت تغییر سیاست نقش‌ها، دادهٔ fixture دو Tenant، فرمان تست، Budget و شرط `DECIDE` برای ابهام مجوز را دارد. Transcript باید دست‌کم یک Observation واقعی و یک Gate پیش از COMPLETE نشان دهد؛ شرح خیالیِ «همه‌چیز درست بود» امتیاز ندارد.

## جمع‌بندی

حلقهٔ ایجنت با مدل شروع می‌شود، اما با مدل قابل‌اعتماد نمی‌شود. دستورهای قابل‌اجرا، Context مرتبط، Tool Call محدود، Observation دقیق، stop condition و هارنسِ پاسخ‌گو آن را به فرایند مهندسی تبدیل می‌کنند. درس بعد می‌پرسد چه Evidenceی واقعاً برای قابلیت و ارزش این حلقه کافی است.

## منابع مستقیم

• [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629) — پژوهش اصلی؛ محیط و معیارهای مقاله، ضمانت محصول عمومی نیست.
• [SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering](https://arxiv.org/abs/2405.15793) — پژوهش اصلی Interface ابزار؛ نتیجه به benchmark و پیکربندی ارزیابی وابسته است.
• [Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — گزارش فروشنده؛ توصیهٔ Workflow و Agent، نه استاندارد ایمنی.
• [OpenAI — Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/) — مستند/شرح رسمی هارنس؛ Surface و رفتار محصول نسخه‌پذیر است.
• [Vitest CLI](https://vitest.dev/guide/cli) — مستند رسمی؛ `vitest run` یک اجرای غیر-watch است و `--maxWorkers` و `--no-file-parallelism` گزینه‌های CLI مستندشده‌اند.

به زبان ساده

حلقهٔ ایجنت از مدل، دستور، Context، ابزار و Observation تشکیل می‌شود و هارنس این رفت‌وبرگشت را محدود می‌کند. پیام «حل شد» جای خروجی فرمان، Diff و شرط پایان را نمی‌گیرد.

مثال واقعی

مقالهٔ ReAct ترکیب استدلال و عمل با بازخورد محیط را بررسی می‌کند؛ این یک الگوی پژوهشی است، نه مدرکی که هر Agent در مخزن واقعی حتماً درست عمل می‌کند.