اگر چند ساعت با یک ایجنت کدنویسی کار کرده باشید، این صحنه را دیدهاید: مدل یک ابزار را صدا میزند، خروجی را میخواند، دوباره همان ابزار را با همان آرگومان صدا میزند و بعد از ده دور، با اعتمادبهنفس کامل میگوید مشکل حل شد؛ در حالی که هیچ فایلی تغییر نکرده است.
مشکل اینجا معمولاً مدل نیست. هارنس است.
هارنس هوش مصنوعی (AI Harness) همان لایهای است که مدل زبانی را اجرا میکند: تعیین میکند مدل به چه ابزارهایی دسترسی دارد، در هر مرحله چه چیزی در کانتکست میبیند، خروجیاش چطور تفسیر میشود، حلقه چه زمانی باید بایستد و کدام کارها بدون تأیید انسان اجازه اجرا ندارند. خود مدل همان وزنها و پیشبینی توکن بعدی است؛ هارنس آن را به یک عامل (Agent) قابلاتکا تبدیل میکند.
این مقاله درباره معماری این لایه است: اجزایش، تصمیمهای عملیاش و اشتباهاتی که در کار روزمره خودمان و تیمهای اطراف دیدهایم.
هارنس در عمل چه کاری انجام میدهد؟
وقتی با API یک مدل زبانی حرف میزنید، یک درخواست میفرستید و یک پاسخ میگیرید. همین. اگر بخواهید مدل چند مرحله کار کند، فایل بخواند، تست اجرا کند یا در دیتابیس جستوجو کند، باید خودتان آن مراحل را طراحی و مدیریت کنید.
هارنس دقیقاً همین مدیریت را بر عهده دارد. برای همین است که یک مدل در دو محصول متفاوت، دو تجربه کاملاً متفاوت میسازد: Claude Code، Codex CLI، Cursor و Copilot از مدلهای مشابهی استفاده میکنند، اما هارنسشان یکی نیست؛ به همین دلیل یکی مسیر درست فایل را پیدا میکند و دیگری مدام در ساختار پروژه گم میشود.
یک هارنس حداقل چهار کار انجام میدهد:
ابزارها را تعریف میکند. مدل نمیتواند فایل بخواند یا دستور شل اجرا کند؛ فقط میتواند بگوید «میخواهم این ابزار را با این آرگومانها صدا بزنم». هارنس آن درخواست را اعتبارسنجی میکند، اجرا میکند و نتیجه را دوباره به مدل برمیگرداند.
کانتکست را میچیند. تصمیم میگیرد در هر دور چه بخشی از تاریخچه، چه فایلهایی و کدام خروجی ابزارها داخل پنجره کانتکست بمانند. این بخش بیشترین اثر را روی کیفیت نهایی دارد و در عمل سختترین قسمت ماجراست.
حلقه را میگرداند. مدل، ابزار، نتیجه و دوباره مدل. هارنس تعیین میکند این چرخه تا کجا ادامه پیدا کند، چه زمانی خلاصهسازی شود و چه زمانی با خطا متوقف شود.
گاردریل میگذارد. محدودیت مسیر فایل، سقف تعداد مراحل، تأیید انسانی برای دستورهای خطرناک، محدودیت هزینه و لاگگیری. بدون این بخش، یک مدل با نیت خوب هم میتواند مخزن کد را به هم بریزد.
| جزء هارنس | سؤال اصلی | نشانه هارنس ضعیف |
|---|---|---|
| تعریف ابزار | مدل دقیقاً چه کاری میتواند بکند؟ | ابزارهای زیاد و مبهم، پارامترهای بدون اعتبارسنجی |
| مدیریت کانتکست | در هر مرحله چه چیزی دیده میشود؟ | ریختن کل تاریخچه در هر درخواست |
| حلقه اجرا | چه زمانی ادامه بدهد و چه زمانی بایستد؟ | حلقه تکراری، پایان زودهنگام |
| گاردریل و ارزیابی | چه چیزی هرگز نباید اتفاق بیفتد؟ | تست دستی، بدون لاگ، بدون سقف هزینه |
هارنس با فریمورک و fine-tune چه تفاوتی دارد؟
این سه مفهوم زیاد قاطی میشوند. Fine-tune رفتار مدل را تغییر میدهد و روی وزنها کار میکند. فریمورک (مثل LangGraph یا ابزارهای مشابه) فقط کد و ساختار میدهد؛ چیزی که با آن هارنس میسازید. RAG هم یک تکنیک تأمین کانتکست است، نه کل هارنس.
هارنس محصول نهایی است: ترکیب پرامپت سیستمی، اسکیمای ابزارها، سیاستهای اجرا، بازیابی اطلاعات و حلقه. به همین دلیل نمیشود آن را با یک کتابخانه نصب کرد. برای هر کار باید طراحی شود — و بعد از هر تغییر مدل یا ابزار، دوباره بازبینی شود.
چطور یک ابزار را درست تعریف کنیم؟
بیشتر خرابیهای ایجنت از تعریف ابزار شروع میشود، نه از پرامپت. یک نمونه بد را با یک نمونه قابلاتکا مقایسه کنید:
{
"name": "search_docs",
"description": "جستوجو در مستندات فنی پروژه. فقط وقتی به اطلاعاتی نیاز داری که در فایلهای باز نیست استفاده کن.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "عبارت جستوجو، حداکثر ۸ کلمه"
},
"scope": {
"type": "string",
"enum": ["api", "deploy", "billing"],
"description": "بخش مستندات"
}
},
"required": ["query"],
"additionalProperties": false
}
}
سه چیز در این تعریف مهم است: توضیح ابزار میگوید چه زمانی از آن استفاده نکند، پارامترها محدود و شمارششدهاند و ورودی اضافی پذیرفته نمیشود. مدلها با فیلدهای آزاد بدرفتاری میکنند و additionalProperties: false جلوی بخشی از این بدرفتاری را میگیرد. اگر خروجی ابزار هم ساختاریافته باشد (مثلاً همیشه {ok, data, error})، تفسیر آن برای مدل سادهتر و پیشبینیپذیرتر میشود.
نکتهای که در ابتدا دستکم میگیریم: توضیح ابزار بخشی از پرامپت است. هر جملهای که آنجا مینویسید هزینه توکن دارد و روی تصمیم مدل اثر میگذارد. توضیح کوتاه و دقیق بهتر از توضیح طولانی و کلی است.
کانتکست: جایی که هارنسها معمولاً شکست میخورند
مدلها پنجره کانتکست بزرگی دارند و همین باعث یک تله میشود: وسوسه میشوید همهچیز را داخلش بریزید. نتیجه را بارها دیدهایم؛ پاسخها کندتر، گرانتر و بیدقتتر میشوند. مدل در انبوه متن، جزئیات مهم را از دست میدهد و چیزهایی را از دورهای قبل به یاد میآورد که دیگر معتبر نیستند.
هارنس خوب بهجای «هرچه هست بفرست»، سه کار میکند:
- خروجی ابزارها را قبل از برگرداندن به مدل کوتاه میکند؛ مثلاً فقط ابتدای لاگ یا خطوط مرتبط با خطا.
- تاریخچه را دورهای خلاصه میکند و تصمیمهای مهم و کارهای انجامشده را نگه میدارد.
- بهجای فایل کامل، بخش مرتبط را میفرستد و مسیر و شماره خط را هم میدهد تا مدل بتواند دقیق ارجاع بدهد.
این تصمیمها چشمگیر نیستند، اما تفاوت بین ایجنتی که کار میکند و ایجنتی که دور خودش میچرخد، معمولاً همینجاست.
حلقه اجرا؛ مهمترین جای تصمیمگیری
حلقه ایجنت ساده به نظر میرسد: پاسخ مدل را بگیر، اگر درخواست ابزار داشت اجرا کن و دوباره بفرست. اما اگر شرط توقف نداشته باشید، همین حلقه ساده به یک ماشین تولید هزینه تبدیل میشود.
چند شرط توقف که حداقل باید داشته باشید:
- سقف مرحله: عدد مشخصی برای تعداد فراخوانی مدل در هر اجرا.
- سقف هزینه و زمان: قطع اجرا وقتی از بودجه تعیینشده عبور کرده است.
- تشخیص تکرار: اگر همان ابزار با همان آرگومانها دو بار پشتسرهم صدا زده شد، یعنی مدل در دام افتاده است. بهجایش به آن بگویید چه چیزی را از قبل میداند.
- خطاهای زنجیرهای: دو یا سه خطای پشتسرهم نشانه خوبی برای توقف و برگرداندن کنترل به انسان است.
- پایان واقعی: فقط پیام متنی بدون درخواست ابزار.
نبود همین شرطها دقیقاً همان چیزی است که در ابتدای مقاله دیدیم: مدل ده بار یک ابزار را صدا میزند و بعد ادعا میکند کار تمام شده.
هارنس مهمتر است یا مدل؟
پاسخ کوتاه: بستگی به کار دارد، اما در بسیاری از کارهای عملی، هارنس سهم بزرگتری دارد. بنچمارکهایی مثل SWE-bench نه فقط مدل، بلکه هارنس را هم میسنجند: نحوه دسترسی به فایلها، امکان اجرای تست و تعداد مراحل مجاز. به همین دلیل نتیجه یک مدل در دو هارنس مختلف میتواند بهطور محسوسی فرق کند.
در کار خودمان، قاعده سادهای داریم: قبل از عوض کردن مدل، سه چیز را بررسی کنید — تعریف ابزارها، کیفیت کانتکستی که میفرستید و اینکه اصلاً معیاری برای سنجش دارید یا نه. در بیشتر موارد، مدل گرانتر مشکل را حل نمیکند؛ هارنس بدترکیبشده مشکل را میسازد.
اشتباهات رایجی که هزینهاش را دادهایم
ابزار زیاد. هر ابزار جدید یک انتخاب اضافه برای مدل است. اگر دو ابزار کار مشابهی میکنند، یکی را حذف کنید. ایجنت با شش ابزار واضح بهتر از ایجنت با سی ابزار همپوشان کار میکند.
نبود سقف برای حلقه. بدون محدودیت مرحله و زمان، یک ابزار خراب کافی است تا مدل دهها بار همان کار را تکرار کند. سقف بگذارید و در صورت رسیدن به سقف، با پیام روشن متوقف شوید؛ نه با حدس و گمان.
اجرای دستور بدون تأیید. مدل نباید بتواند هر دستوری را روی سرور اجرا کند. لیست سفید دستورها، محدود کردن مسیرها و تأیید انسانی برای عملیات مخرب (حذف فایل، push کردن، تغییر تنظیمات شبکه) حداقل کار است.
ارزیابی دستی. اگر فقط چند پرامپت را دستی امتحان کردهاید، هارنس ندارید؛ دمو دارید. یک مجموعه کوچک از سناریوهای تکراری با خروجی مورد انتظار بسازید و بعد از هر تغییر همانها را اجرا کنید. حتی بیست سناریو هم از هیچ بهتر است.
کلید و راز در کانتکست. فایل محیطی (.env)، توکنها و داده مشتریان نباید به مدل برسند. این را در هارنس فیلتر کنید، نه در پرامپت. مدل نمیتواند چیزی را که ندیده است لو بدهد.
چکلیست قبل از production
- سقف مرحله، زمان و هزینه برای هر اجرا تعیین شده است.
- هر ابزار توضیح روشن، پارامتر محدود و اعتبارسنجی ورودی دارد.
- خروجی ابزارها کوتاه و ساختاریافته است و لاگ هر مرحله ذخیره میشود.
- عملیات خطرناک فقط با تأیید انسان اجرا میشوند.
- مجموعهای از سناریوهای تست با نتیجه قابلتکرار دارید.
- مسیر فایلها و دامنه دسترسی محدود است.
- هزینه هر اجرا اندازهگیری میشود؛ نه در ذهن، در داشبورد.
اجرای هارنس روی زیرساخت خودتان
هارنس یک قطعه نرمافزاری است و باید جایی اجرا شود. برای تیمهایی که داده حساس دارند، اجرای مدلهای open-source و هارنس روی سرور خودشان گزینه منطقیتری است: کانتکست از شبکه شما بیرون نمیرود و کنترل هزینه سادهتر میشود. برای شروع، راهنمای Docker روی VPS و مقاله VPS چیست نقطه خوبی است.
اگر هم فقط ابزارهای API-محور را اجرا میکنید، یک سرور کوچک با منابع قابل ارتقا کافی است؛ مهمتر از قدرت پردازش، پایداری شبکه و امکان مانیتورینگ است. در صفحه پلنهای افرادین میتوانید منابع لازم را متناسب با حجم اجرا انتخاب کنید.
جمعبندی
هارنس جای مدل را نمیگیرد و مدل جای هارنس را. اما اگر امروز یک ایجنت میسازید و نتیجهاش قابلاتکا نیست، احتمالاً جای درستی از سیستم را بررسی نمیکنید. قبل از خرید مدل گرانتر یا بازنویسی پرامپت، ببینید مدل چه ابزارهایی دارد، چه چیزی میبیند و چه زمانی متوقف میشود.
بهترین هارنسها هم سادهاند: ابزار کم و روشن، کانتکست کوتاه و مربوط، سقف مشخص و لاگ کامل. بقیهاش جزئیات است؛ جزئیاتی که در روزهای اول کمتر به چشم میآیند و در روزهای سخت، همهچیز را تعیین میکنند.
مقالات مرتبط
- آیا هوش مصنوعی جای برنامهنویسها را میگیرد؟ — بررسی تغییر نقش برنامهنویس در عصر هوش مصنوعی
- کاربردیسازی هوش مصنوعی در کسبوکارهای ایرانی — از هیجان تا ارزش واقعی
- Docker روی VPS — راهنمای کامل نصب و اجرا — اجرای سرویسهای self-hosted روی سرور خودتان
- VPS چیست؟ راهنمای کامل و جامع — زیرساخت پایه برای اجرای ایجنت و مدل