Agentic Harness چیست؟ تفاوت مدل هوش مصنوعی و AI Agent

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

دلیل این تفاوت همیشه قدرت مدل نیست.

بخش مهمی از عملکرد یک AI Agent به لایه نرم‌افزاری اطراف مدل بستگی دارد؛ لایه‌ای که ابزارها، دستورها، حافظه، Context، حلقه اجرا، مدیریت وضعیت و روش ارزیابی نتیجه را در کنار یکدیگر قرار می‌دهد.

به این لایه Agentic Harness یا AI Agent Harness گفته می‌شود.

مدل هوش مصنوعی توانایی تحلیل و تولید پاسخ را فراهم می‌کند، اما Harness مشخص می‌کند مدل:

• چه اطلاعاتی دریافت کند؛
• به چه ابزارهایی دسترسی داشته باشد؛
• چگونه ابزار مناسب را انتخاب کند؛
• نتیجه اجرای ابزار را چگونه ببیند؛
• چه زمانی کار را ادامه دهد؛
• چه زمانی متوقف شود؛
• و چگونه نتیجه نهایی را تحویل دهد.

بنابراین هنگام ساخت یک عامل هوش مصنوعی، انتخاب مدل فقط یکی از تصمیم‌های معماری است. کیفیت Harness نیز می‌تواند مستقیماً بر نتیجه نهایی اثر بگذارد.

Agentic Harness چیست؟

Agentic Harness مجموعه‌ای از اجزای نرم‌افزاری است که پیرامون یک مدل هوش مصنوعی قرار می‌گیرد و امکان انجام وظایف چندمرحله‌ای، استفاده از ابزار، مدیریت Context و ادامه کار تا رسیدن به نتیجه را فراهم می‌کند.

یک مدل زبانی به‌تنهایی معمولاً ورودی را دریافت و خروجی متنی تولید می‌کند:

درخواست کاربر
↓
مدل هوش مصنوعی
↓
پاسخ

اما یک Agentic Harness جریان کامل‌تری ایجاد می‌کند:

درخواست کاربر
↓
آماده‌سازی دستور و Context
↓
ارسال درخواست به مدل
↓
انتخاب ابزار
↓
اجرای ابزار در برنامه
↓
بازگرداندن نتیجه به مدل
↓
ادامه تحلیل یا اجرای ابزار دیگر
↓
بررسی شرط پایان
↓
پاسخ نهایی

در این معماری، مدل همچنان بخش استدلالی سیستم است؛ اما Harness ارتباط میان مدل، ابزارها، داده‌ها و چرخه اجرا را مدیریت می‌کند.

Anthropic در راهنمای ارزیابی Agentهای هوش مصنوعی، Agent Harness یا Scaffold را سیستمی توصیف می‌کند که به مدل امکان رفتار عامل‌محور می‌دهد؛ یعنی ورودی‌ها را پردازش می‌کند، فراخوانی ابزارها را هماهنگ می‌کند و نتیجه را برمی‌گرداند.

آیا Agentic Harness یک استاندارد رسمی است؟

خیر. Agentic Harness هنوز یک اصطلاح کاملاً استاندارد با تعریف واحد و قطعی نیست.

در منابع مختلف ممکن است اصطلاحات زیر را ببینید:

• Agent Harness
• Agentic Harness
• Agent Scaffold
• Agent Runtime
• Agent Framework
• Agent Orchestrator
• Agent Loop
• Agent System

این اصطلاحات گاهی به بخش‌های متفاوت و گاهی به اجزای هم‌پوشان اشاره می‌کنند.

LangChain نیز در توضیح تفاوت Framework، Runtime و Harness اشاره می‌کند که Agent Harnessها معمولاً چارچوب‌هایی نسبتاً کامل و دارای ابزارهای داخلی برای ساخت عامل‌های پیشرفته و طولانی‌مدت هستند.

بنابراین هنگام مطالعه مستندات یک محصول، نباید فقط به نام آن توجه کرد. باید بررسی شود آن محصول دقیقاً کدام قابلیت‌ها را ارائه می‌دهد.

تفاوت مدل هوش مصنوعی و Agentic Harness

مدل هوش مصنوعی و Harness دو نقش متفاوت دارند.

فرض کنید از یک Agent بخواهیم:

سه محصول مناسب برای یک فروشگاه کوچک پیدا کن، آن‌ها را مقایسه کن و یک پیشنهاد کوتاه بساز.

مدل می‌تواند درخواست را بفهمد و درباره مراحل کار تصمیم بگیرد؛ اما به‌تنهایی به فهرست واقعی محصولات دسترسی ندارد.

Harness باید:

1. ابزار جست‌وجوی محصول را در اختیار مدل قرار دهد.
2. تعریف و پارامترهای ابزار را به مدل معرفی کند.
3. درخواست استفاده از ابزار را از پاسخ مدل استخراج کند.
4. تابع جست‌وجو را اجرا کند.
5. نتایج را دوباره به Context مدل اضافه کند.
6. در صورت نیاز اجازه اجرای مرحله بعدی را بدهد.
7. پاسخ نهایی را دریافت کند.

اگر هرکدام از این مراحل درست طراحی نشده باشد، حتی یک مدل قوی نیز ممکن است نتیجه مناسبی تولید نکند.

تفاوت AI Agent و Agent Harness

AI Agent همان سامانه‌ای است که کاربر با آن تعامل می‌کند. Agent Harness بخشی از معماری داخلی این سامانه است.

برای مثال، یک عامل فروشگاهی می‌تواند:

• نیاز کاربر را تحلیل کند؛
• محصولات را جست‌وجو کند؛
• ویژگی‌ها را مقایسه کند؛
• نتیجه را خلاصه کند؛
• و چند گزینه پیشنهاد دهد.

اما Harness زیرساختی است که این رفتار را امکان‌پذیر می‌کند:

• مدل را فراخوانی می‌کند؛
• ابزار جست‌وجوی محصول را اجرا می‌کند؛
• پیام‌ها را مدیریت می‌کند؛
• وضعیت مراحل را نگه می‌دارد؛
• تعداد تکرارها را کنترل می‌کند؛
• و نتیجه نهایی را تحویل می‌دهد.

به زبان ساده، کاربر Agent را می‌بیند، اما Harness در پشت صحنه Agent را هدایت می‌کند.

برای آشنایی با مفهوم کلی عامل هوشمند می‌توانید مقاله AI Agent و Agent Skills چیست؟ را مطالعه کنید.

تفاوت Agent Harness، Agent Framework و Agent Runtime

این اصطلاحات نزدیک‌اند، اما می‌توان آن‌ها را براساس نقش اصلی از هم جدا کرد.

مرز میان این لایه‌ها همیشه دقیق نیست. یک محصول می‌تواند هم‌زمان بخشی از Framework، Runtime و Harness را ارائه کند.

برای مثال:

• LangChain بیشتر به‌عنوان Framework شناخته می‌شود.
• LangGraph قابلیت‌های Runtime و هماهنگی Workflow را ارائه می‌کند.
• Deep Agents یک Harness کامل‌تر برای عامل‌های طولانی‌مدت ارائه می‌دهد.
• Google ADK اجزایی برای ساخت Agent، Session، State، Tool و Runtime دارد.
• یک Harness اختصاصی نیز می‌تواند مستقیماً با Python و API ساخته شود.

مهم‌ترین اجزای Agentic Harness

۱. Model Client

Model Client ارتباط با مدل هوش مصنوعی را مدیریت می‌کند.

وظایف آن می‌تواند شامل موارد زیر باشد:

• ارسال پیام‌ها
• تعیین Model ID
• تنظیم پارامترها
• دریافت پاسخ
• پردازش Tool Call
• مدیریت خطاهای API
• ثبت میزان مصرف

در یک معماری چندمدلی، Model Client می‌تواند مدل مناسب هر وظیفه را نیز انتخاب کند.

درواره یک API سازگار با OpenAI ارائه می‌کند. بنابراین می‌توان بسیاری از SDKها و فریم‌ورک‌های سازگار را با Base URL زیر به مدل‌های ارائه‌شده در درواره متصل کرد:

https://api.darvareh.ir/v1

۲. System Instructions

دستور سیستمی نقش و محدوده فعالیت Agent را مشخص می‌کند.

یک دستور مناسب باید روشن کند:

• هدف Agent چیست؛
• چه ابزارهایی در اختیار دارد؛
• چه زمانی از هر ابزار استفاده کند؛
• خروجی نهایی چه ساختاری داشته باشد؛
• در صورت ناقص‌بودن اطلاعات چه رفتاری انجام دهد؛
• و چه زمانی کار را متوقف کند.

دستور بیش از حد کلی باعث می‌شود Agent رفتار نامنظمی داشته باشد.

نمونه ضعیف:

به کاربر کمک کن و هر کاری لازم است انجام بده.

نمونه دقیق‌تر:

شما دستیار انتخاب محصول هستید.
ابتدا نیاز کاربر را مشخص کنید.
برای مشاهده محصولات فقط از ابزار search_product_catalog استفاده کنید.
ویژگی یا قیمتی را خارج از نتیجه ابزار ایجاد نکنید.
در پایان حداکثر سه گزینه را همراه با دلیل پیشنهاد دهید.

۳. Tool Registry

Tool Registry فهرست ابزارهایی است که Agent اجازه دارد از آن‌ها استفاده کند.

هر ابزار باید حداقل شامل این اطلاعات باشد:

• نام مشخص
• توضیح کوتاه و دقیق
• پارامترهای ورودی
• نوع هر پارامتر
• فیلدهای ضروری
• تابع اجرایی متناظر

نمونه ابزارها:

• جست‌وجوی محصول
• خواندن اطلاعات سفارش
• جست‌وجوی اسناد
• اجرای Query
• دریافت وضعیت پروژه
• ساخت گزارش
• فراخوانی یک API
• ثبت پیش‌نویس در نرم‌افزار

مدل ابزار را مستقیماً اجرا نمی‌کند. مدل نام ابزار و آرگومان‌های پیشنهادی را تولید می‌کند و Harness تابع واقعی را اجرا می‌کند.

برای توضیح کامل این فرایند می‌توانید راهنمای Function Calling چیست؟ را مطالعه کنید.

۴. Agent Loop

Agent Loop چرخه‌ای است که مدل و ابزارها را به یکدیگر متصل می‌کند.

چرخه ساده Agent:

1. ارسال هدف و Context به مدل
2. دریافت پاسخ مدل
3. بررسی وجود Tool Call
4. اجرای ابزار
5. افزودن نتیجه ابزار به پیام‌ها
6. ارسال دوباره پیام‌ها به مدل
7. تکرار تا دریافت پاسخ نهایی یا رسیدن به شرط توقف

بدون این حلقه، مدل فقط می‌تواند پیشنهاد دهد که ابزاری اجرا شود؛ اما فرایند بعد از پیشنهاد متوقف خواهد شد.

۵. Context Manager

Context Manager مشخص می‌کند در هر مرحله چه اطلاعاتی به مدل ارسال شود.

Context می‌تواند شامل این موارد باشد:

• درخواست فعلی کاربر
• تاریخچه مراحل
• نتیجه ابزارها
• دستورهای سیستمی
• اطلاعات مرتبط بازیابی‌شده
• وضعیت فعلی وظیفه
• خلاصه مراحل قبلی
• تعریف ابزارهای فعال

ارسال تمام اطلاعات موجود همیشه روش مناسبی نیست. Context بزرگ و پراکنده می‌تواند هزینه را افزایش دهد و تمرکز مدل را کاهش دهد.

Harness باید اطلاعات مرتبط را انتخاب، خلاصه یا در زمان مناسب حذف کند.

Anthropic در راهنمای Context Engineering برای Agentها توضیح می‌دهد که فشرده‌سازی تاریخچه و حفظ تصمیم‌ها و اطلاعات مهم می‌تواند امکان ادامه وظایف طولانی را فراهم کند.

مقاله Context Engineering چیست؟ نیز این موضوع را به‌صورت کامل بررسی می‌کند.

۶. State Management

State وضعیت فعلی اجرای Agent را نگه می‌دارد.

نمونه State:

{
  "task_id": "task-1042",
  "status": "searching_products",
  "steps_completed": 2,
  "selected_category": "accounting_software",
  "candidate_count": 8
}

تاریخچه پیام و State یکسان نیستند.

تاریخچه پیام نشان می‌دهد چه گفتگو یا اقداماتی انجام شده است. State اطلاعات ساختاریافته‌ای است که برنامه برای ادامه فرایند نیاز دارد.

طبق مستندات Session و State در Google ADK، Session تعامل جاری و رویدادهای آن را نگه می‌دارد و State مانند فضای کاری ساختاریافته همان تعامل عمل می‌کند.

۷. Memory

حافظه اطلاعاتی را نگه می‌دارد که ممکن است در مراحل یا اجراهای بعدی موردنیاز باشند.

انواع حافظه می‌تواند شامل موارد زیر باشد:

• حافظه همان Session
• خلاصه مکالمات قبلی
• اطلاعات مربوط به وظیفه
• نتایج ابزارها
• ترجیحات کاری تعریف‌شده
• تجربه‌های ثبت‌شده از اجرای قبلی

Harness باید مشخص کند:

• چه چیزی ذخیره شود؛
• چه زمانی بازیابی شود؛
• چه زمانی خلاصه شود؛
• و چه بخشی وارد Context مدل شود.

ذخیره‌کردن همه پیام‌ها بدون انتخاب و خلاصه‌سازی معمولاً حافظه مفیدی ایجاد نمی‌کند.

۸. Skill System

Skill مجموعه‌ای از دستورها و منابع قابل‌استفاده مجدد برای انجام یک وظیفه تخصصی است.

برای مثال، یک Agent تولید محتوا می‌تواند Skillهای جداگانه‌ای داشته باشد:

• تحقیق کلمه کلیدی
• طراحی ساختار مقاله
• بازنویسی فارسی
• ساخت توضیحات متا
• کنترل لینک‌های داخلی
• تولید FAQ

Skill با Tool تفاوت دارد.

Tool یک عملیات مشخص را اجرا می‌کند؛ اما Skill روش انجام یک کار تخصصی را برای Agent توضیح می‌دهد و می‌تواند از چند ابزار استفاده کند.

۹. Output Validation

Agent ممکن است پاسخ متنی یا ساختاریافته تولید کند. Harness باید بررسی کند خروجی با قالب مورد انتظار مطابقت دارد.

برای خروجی JSON می‌توان موارد زیر را بررسی کرد:

• وجود فیلدهای ضروری
• نوع صحیح داده‌ها
• معتبر بودن مقادیر
• محدودیت طول
• تعداد آیتم‌ها
• امکان تبدیل پاسخ به ساختار برنامه

برای آشنایی بیشتر، مقاله Structured Outputs چیست؟ را بخوانید.

۱۰. Stop Conditions

Agent باید بداند چه زمانی اجرای وظیفه را متوقف کند.

شرایط توقف می‌تواند شامل این موارد باشد:

• تولید پاسخ نهایی
• تکمیل تمام مراحل
• رسیدن به حداکثر تعداد تکرار
• نبود ابزار مناسب
• دریافت نتیجه کافی
• تکرارشدن یک اقدام
• پایان زمان اجرای تعریف‌شده
• رسیدن مصرف به سقف تعیین‌شده

اگر شرط توقف وجود نداشته باشد، Agent ممکن است ابزارها را بی‌دلیل چند بار اجرا کند یا وارد چرخه تکراری شود.

۱۱. Evaluation Layer

عملکرد Agent فقط با مشاهده چند پاسخ خوب قابل‌ارزیابی نیست.

باید مجموعه‌ای از وظایف واقعی تهیه شود و این موارد اندازه‌گیری شوند:

• درصد تکمیل موفق وظیفه
• انتخاب صحیح ابزار
• صحت آرگومان‌های Tool Call
• تعداد مراحل اجرا
• زمان رسیدن به نتیجه
• مصرف API
• کیفیت پاسخ نهایی
• نرخ نیاز به اصلاح
• میزان تکرار عملیات غیرضروری

هنگام ارزیابی یک Agent، در واقع ترکیب مدل و Harness ارزیابی می‌شود. تغییر مدل، Prompt، تعریف ابزار یا مدیریت Context می‌تواند نتیجه را تغییر دهد.

چرا مدل قوی همیشه Agent بهتری نمی‌سازد؟

مدل قوی‌تر معمولاً توانایی بیشتری در استدلال، برنامه‌ریزی و استفاده از ابزار دارد؛ اما Harness نامناسب می‌تواند بخش بزرگی از این توانایی را هدر دهد.

تعریف نامناسب ابزار

اگر توضیح دو ابزار بسیار شبیه باشد، مدل ممکن است ابزار اشتباه را انتخاب کند.

Context پراکنده

اگر پیام‌ها، اسناد و نتایج ابزار بدون اولویت وارد Context شوند، اطلاعات مهم میان جزئیات غیرضروری گم می‌شوند.

نتیجه ابزار بیش از حد طولانی

بازگرداندن صدها رکورد به مدل می‌تواند هزینه را افزایش دهد و انتخاب نتیجه درست را دشوار کند.

نبود State مشخص

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

شرط توقف ضعیف

Agent ممکن است پس از رسیدن به پاسخ کافی، همچنان ابزار اجرا کند یا میان دو مرحله تکراری باقی بماند.

نبود ارزیابی واقعی

ممکن است Agent در یک نمایش کوتاه خوب عمل کند، اما روی عبارت‌بندی‌ها و سناریوهای واقعی کاربران نتیجه متفاوتی داشته باشد.

به همین دلیل، بهبود Agent همیشه با تعویض مدل آغاز نمی‌شود. ابتدا باید مشخص شود مشکل از توانایی مدل است یا از طراحی Harness.

Harness Engineering چیست؟

Harness Engineering به طراحی و بهبود سیستم نرم‌افزاری اطراف مدل گفته می‌شود.

در Prompt Engineering تمرکز اصلی بر نوشتن دستور بهتر است. در Context Engineering تمرکز بر انتخاب و مدیریت اطلاعات ورودی مدل قرار دارد. Harness Engineering سطح گسترده‌تری را پوشش می‌دهد:

• انتخاب مدل
• طراحی Prompt
• مدیریت Context
• تعریف ابزارها
• Agent Loop
• State و Memory
• Skillها
• مدیریت خروجی
• شرط‌های توقف
• ارزیابی
• مدل‌گزینی در زمان اجرا

مقاله Databricks درباره AI Agent Harness نیز Harness را زیرساخت نرم‌افزاری اطراف مدل معرفی می‌کند که ابزارها، حافظه و محیط اجرای لازم را برای انجام وظایف واقعی فراهم می‌سازد.

Agentic Harness برای وظایف طولانی‌مدت

هرچه وظیفه طولانی‌تر شود، نقش Harness مهم‌تر خواهد شد.

در یک درخواست کوتاه، مدل ممکن است با یک پاسخ مسئله را حل کند. اما وظیفه‌ای مانند بررسی یک پروژه نرم‌افزاری، تحقیق چندمنبعی یا پردازش صدها سند می‌تواند شامل مراحل زیادی باشد.

Harness برای چنین وظایفی باید بتواند:

• پیشرفت کار را ثبت کند؛
• نتایج میانی را نگه دارد؛
• Context را فشرده کند؛
• وظیفه را پس از وقفه ادامه دهد؛
• مراحل تکمیل‌شده را تشخیص دهد؛
• و از اجرای دوباره کارهای قبلی جلوگیری کند.

Anthropic در مقاله Effective Harnesses for Long-Running Agents نشان می‌دهد که مدیریت پیشرفت، خلاصه‌سازی Context و ایجاد ساختار مناسب برای ادامه کار، از اجزای مهم Agentهای طولانی‌مدت هستند.

آموزش ساخت Agentic Harness ساده با Python و API درواره

در این مثال یک Harness کوچک برای دستیار انتخاب محصول می‌سازیم.

Agent می‌تواند با استفاده از یک ابزار محلی، فهرست محصولات را جست‌وجو و براساس نیاز کاربر پیشنهاد ارائه کند.

پیش‌نیاز

pip install openai

متغیرهای محیطی:

export DARVAREH_API_KEY="YOUR_API_KEY"
export DARVAREH_MODEL_ID="YOUR_MODEL_ID"

مدلی را انتخاب کنید که از Tool Calling پشتیبانی کند. قابلیت‌های هر مدل را براساس فهرست فعلی مدل‌های درواره بررسی و قبل از استفاده در پروژه واقعی آزمایش کنید.

تعریف داده و ابزار

PRODUCTS = [
    {
        "name": "فروش‌یار پایه",
        "category": "crm",
        "team_size": "small",
        "description": "مدیریت سرنخ و پیگیری فروش برای تیم‌های کوچک"
    },
    {
        "name": "فروش‌یار حرفه‌ای",
        "category": "crm",
        "team_size": "medium",
        "description": "مدیریت فروش، گزارش و گردش‌کار برای تیم‌های متوسط"
    },
    {
        "name": "پاسخ‌یار",
        "category": "support",
        "team_size": "small",
        "description": "مدیریت درخواست‌های پشتیبانی و پایگاه دانش"
    }
]


def search_product_catalog(category: str, team_size: str) -> list:
    return [
        product
        for product in PRODUCTS
        if product["category"] == category
        and product["team_size"] == team_size
    ]

معرفی ابزار به مدل

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "search_product_catalog",
            "description": (
                "محصولات موجود را براساس دسته و اندازه تیم جست‌وجو می‌کند."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "category": {
                        "type": "string",
                        "enum": ["crm", "support"],
                        "description": "دسته محصول"
                    },
                    "team_size": {
                        "type": "string",
                        "enum": ["small", "medium"],
                        "description": "اندازه تیم"
                    }
                },
                "required": ["category", "team_size"],
                "additionalProperties": False
            }
        }
    }
]

ساخت Model Client

import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url="https://api.darvareh.ir/v1"
)

MODEL_ID = os.environ["DARVAREH_MODEL_ID"]

اجرای ابزار

def execute_tool(tool_name: str, arguments: dict):
    if tool_name == "search_product_catalog":
        return search_product_catalog(
            category=arguments["category"],
            team_size=arguments["team_size"]
        )

    raise ValueError(f"Unknown tool: {tool_name}")

Harness فقط ابزارهای ثبت‌شده را اجرا می‌کند. مدل نمی‌تواند نام یک تابع جدید را به برنامه تحمیل کند.

ساخت Agent Loop

def run_agent(user_message: str, max_steps: int = 4) -> str:
    messages = [
        {
            "role": "system",
            "content": (
                "شما دستیار انتخاب محصول هستید. "
                "برای مشاهده محصولات فقط از ابزار موجود استفاده کنید. "
                "اطلاعاتی خارج از نتیجه ابزار ایجاد نکنید. "
                "در پایان حداکثر سه گزینه مناسب پیشنهاد دهید."
            )
        },
        {
            "role": "user",
            "content": user_message
        }
    ]

    for _ in range(max_steps):
        response = client.chat.completions.create(
            model=MODEL_ID,
            messages=messages,
            tools=TOOLS,
            tool_choice="auto",
            temperature=0
        )

        assistant_message = response.choices[0].message
        messages.append(
            assistant_message.model_dump(exclude_none=True)
        )

        if not assistant_message.tool_calls:
            return assistant_message.content or ""

        for tool_call in assistant_message.tool_calls:
            arguments = json.loads(
                tool_call.function.arguments
            )

            tool_result = execute_tool(
                tool_name=tool_call.function.name,
                arguments=arguments
            )

            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": json.dumps(
                        tool_result,
                        ensure_ascii=False
                    )
                }
            )

    return "اجرای Agent پیش از رسیدن به پاسخ نهایی متوقف شد."

اجرای Agent

result = run_agent(
    "برای یک تیم فروش پنج‌نفره یک CRM ساده می‌خواهم. "
    "کدام محصول مناسب‌تر است؟"
)

print(result)

اجزای Harness در این مثال

کدی که نوشتیم فقط یک درخواست ساده به مدل نیست. چند جزء اصلی Harness در آن وجود دارد:

در یک پروژه واقعی می‌توان اجزای دیگری نیز اضافه کرد:

• State ساختاریافته
• حافظه
• ابزارهای بیشتر
• ثبت مراحل اجرا
• ارزیابی خودکار
• انتخاب چند مدل
• Workflowهای چندمرحله‌ای
• بازیابی اطلاعات با RAG
• اجرای موازی بعضی وظایف

نقش API درواره در Agentic Harness

Agentic Harness به یک مدل خاص محدود نیست. مدل باید مانند یک جزء قابل‌تعویض در معماری در نظر گرفته شود.

ممکن است برای وظایف مختلف به مدل‌های متفاوتی نیاز داشته باشید:

• مدل سریع برای دسته‌بندی
• مدل دقیق‌تر برای برنامه‌ریزی
• مدل مناسب برنامه‌نویسی
• مدل چندوجهی برای تحلیل تصویر
• مدل سبک برای بررسی خروجی
• مدل قوی‌تر برای موارد پیچیده

اگر برای هر مدل یک API جداگانه استفاده شود، Harness باید چند روش اتصال، چند کلید و چند قالب پاسخ را مدیریت کند.

درواره با ارائه یک API سازگار با OpenAI، امکان اتصال به مدل‌های مختلف را از طریق Base URL مشترک فراهم می‌کند. در بسیاری از پروژه‌ها می‌توان مدل را با تغییر Model ID جایگزین کرد و بخش اصلی Harness را ثابت نگه داشت.

نمونه Model Client:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DARVAREH_API_KEY",
    base_url="https://api.darvareh.ir/v1"
)

مزایای این معماری عبارت‌اند از:

• استفاده از یک API برای مدل‌های مختلف
• پرداخت ریالی
• مدیریت متمرکز مصرف
• امکان آزمایش چند مدل
• کاهش وابستگی Harness به یک ارائه‌دهنده
• انتخاب مدل متناسب با هر مرحله
• حفظ معماری اصلی هنگام تغییر مدل

برای دریافت Model ID معتبر، فهرست فعلی مدل‌ها و قابلیت‌های هر مدل را در درواره بررسی کنید.

چگونه تشخیص دهیم مشکل از مدل است یا Harness؟

اگر Agent نتیجه مناسبی تولید نمی‌کند، بلافاصله مدل را تعویض نکنید. ابتدا محل خطا را مشخص کنید.

مدل درخواست را درست نمی‌فهمد

یک مدل دیگر را با همان Prompt و Context آزمایش کنید.

مدل ابزار اشتباه را انتخاب می‌کند

نام و توضیح ابزارها را بررسی کنید. ابزارهای دارای نقش مشابه را از هم متمایز کنید.

آرگومان Tool Call ناقص است

Schema ابزار، فیلدهای ضروری و توضیح پارامترها را دقیق‌تر کنید.

Agent مراحل را تکرار می‌کند

State و شرط توقف را بررسی کنید و نتیجه مراحل تکمیل‌شده را به شکل روشن در Context قرار دهید.

Agent اطلاعات مهم را فراموش می‌کند

مدیریت Context، خلاصه مراحل و State ساختاریافته را بهبود دهید.

هزینه اجرای Agent زیاد است

تعداد مراحل، اندازه نتیجه ابزارها، طول Context و مدل مورداستفاده در هر مرحله را بررسی کنید.

پاسخ نهایی ضعیف است

مشخص کنید آیا اطلاعات کافی از ابزارها دریافت شده است یا مدل با وجود Context مناسب، نتیجه ضعیفی ساخته است.

این روش کمک می‌کند به‌جای ارتقای بی‌هدف مدل، همان لایه‌ای را اصلاح کنید که واقعاً باعث خطا شده است.

آیا باید Agentic Harness را از ابتدا بنویسیم؟

همیشه نه. انتخاب میان Harness اختصاصی و فریم‌ورک آماده به پیچیدگی پروژه بستگی دارد.

Harness اختصاصی مناسب است اگر:

• تعداد ابزارها محدود است؛
• Workflow ساده و مشخص است؛
• کنترل مستقیم روی Agent Loop می‌خواهید؛
• وابستگی کمتر به فریم‌ورک اهمیت دارد؛
• تیم فنی می‌خواهد رفتار سیستم را دقیقاً مدیریت کند.

فریم‌ورک آماده مناسب است اگر:

• Agent چندین ابزار دارد؛
• State و Memory پیچیده است؛
• اجرای طولانی‌مدت نیاز دارید؛
• چند Agent با یکدیگر همکاری می‌کنند؛
• Workflow شاخه‌ای یا حلقه‌ای دارید؛
• به قابلیت‌های آماده برای ارزیابی و مدیریت اجرا نیاز دارید.

گزینه‌های متن‌باز و قابل‌استقرار روی زیرساخت شخصی شامل LangChain، LangGraph، Deep Agents، LlamaIndex Workflows و Google ADK هستند. پیش از انتخاب، قابلیت‌های واقعی موردنیاز پروژه را مشخص کنید و سپس ساده‌ترین گزینه متناسب را انتخاب کنید.

اشتباهات رایج در طراحی Agentic Harness

شروع با ابزارهای بیش از حد

افزودن تعداد زیادی ابزار در نسخه اول، انتخاب ابزار را برای مدل دشوارتر و ارزیابی سیستم را پیچیده‌تر می‌کند.

با چند ابزار محدود و کاملاً متمایز شروع کنید.

نوشتن توضیح مبهم برای ابزار

توضیح زیر کافی نیست:

اطلاعات را جست‌وجو می‌کند.

توضیح دقیق‌تر:

محصولات موجود در کاتالوگ را براساس دسته محصول و اندازه تیم جست‌وجو می‌کند.

استفاده از تاریخچه پیام به‌جای State

اگر اطلاعات مهم فقط داخل صدها پیام نگهداری شوند، بازیابی وضعیت جاری دشوار خواهد شد. وضعیت مراحل را در یک ساختار جداگانه ثبت کنید.

بازگرداندن خروجی خام و طولانی ابزار

نتایج ابزار را فیلتر و فقط اطلاعات موردنیاز مرحله بعد را وارد Context کنید.

نداشتن حداکثر مرحله

برای هر اجرای Agent تعداد مرحله، زمان و مصرف قابل‌قبولی تعیین کنید.

ترکیب تمام وظایف در یک Agent

گاهی چند Workflow کوچک و تخصصی، بهتر از یک Agent عمومی بسیار پیچیده عمل می‌کنند.

ارزیابی فقط با مثال‌های ساده

Agent را با نمونه‌های ناقص، مبهم، طولانی و خارج از الگوی معمول نیز آزمایش کنید.

تعویض دائمی مدل بدون اصلاح معماری

مدل بهتر نمی‌تواند تمام مشکلات ابزار، Context، State و حلقه اجرا را جبران کند.

چک‌لیست ساخت Agentic Harness

پیش از انتشار یک Agent بررسی کنید:

• هدف Agent دقیق و محدود تعریف شده است.
• نقش مدل در معماری مشخص است.
• ابزارها نام و توضیح متمایز دارند.
• Schema ورودی ابزارها کامل است.
• فقط ابزارهای ثبت‌شده اجرا می‌شوند.
• نتیجه ابزارها به قالب مناسب تبدیل می‌شود.
• Context هر مرحله کنترل می‌شود.
• State جدا از تاریخچه پیام نگهداری می‌شود.
• شرط پایان تعریف شده است.
• حداکثر تعداد مراحل مشخص است.
• خروجی نهایی اعتبارسنجی می‌شود.
• مصرف هر اجرا ثبت می‌شود.
• چند مدل روی داده واقعی مقایسه شده‌اند.
• مجموعه ارزیابی قابل‌تکرار وجود دارد.
• شکست‌های Agent برای اصلاح Harness تحلیل می‌شوند.

آینده Harness Engineering

با قوی‌ترشدن مدل‌ها، اهمیت Harness کمتر نمی‌شود؛ بلکه نوع طراحی آن تغییر می‌کند.

مدل‌های جدید می‌توانند ابزارهای بیشتری را درک کنند، وظایف طولانی‌تری انجام دهند و برنامه‌های دقیق‌تری بسازند. در مقابل، Harness باید بتواند این توانایی را به نتیجه قابل‌استفاده تبدیل کند.

مسیر توسعه Agentها به سمت این قابلیت‌ها حرکت می‌کند:

• Context پویا
• انتخاب ابزار براساس مرحله
• تغییر مدل در زمان اجرا
• Skillهای قابل‌استفاده مجدد
• حافظه ساختاریافته
• Agentهای تخصصی
• اجرای طولانی‌مدت
• ارزیابی مستمر
• فشرده‌سازی خودکار Context
• جداسازی مدل از لایه اجرا

در این معماری، رقابت فقط میان مدل‌ها نیست. کیفیت سیستم پیرامون مدل نیز به یکی از عوامل اصلی موفقیت محصولات Agentمحور تبدیل می‌شود.

پرسش‌های متداول

Agentic Harness چیست؟

Agentic Harness لایه نرم‌افزاری پیرامون مدل هوش مصنوعی است که ابزارها، Context، حافظه، State و حلقه اجرای Agent را مدیریت می‌کند.

تفاوت مدل هوش مصنوعی و Agentic Harness چیست؟

مدل وظیفه تحلیل و تولید خروجی را انجام می‌دهد. Harness مشخص می‌کند مدل چه اطلاعات و ابزارهایی دریافت کند و مراحل Agent چگونه اجرا شوند.

آیا Agentic Harness همان AI Agent است؟

خیر. AI Agent سامانه کامل قابل‌استفاده است. Agentic Harness لایه‌ای درون آن است که مدل و ابزارها را هماهنگ می‌کند.

تفاوت Agent Framework و Agent Harness چیست؟

Framework ابزارهای برنامه‌نویسی پایه برای ساخت Agent ارائه می‌دهد. Harness معمولاً ساختار کامل‌تر و آماده‌تری شامل ابزار، حافظه، Context و الگوی اجرای وظایف دارد. مرز میان این اصطلاحات همیشه کاملاً ثابت نیست.

آیا Agentic Harness بدون مدل کار می‌کند؟

خیر. Harness برای هدایت و اجرای رفتار یک مدل طراحی شده است. بدون مدل، بخش استدلال و انتخاب اقدام وجود نخواهد داشت.

آیا یک مدل ضعیف با Harness خوب بهتر می‌شود؟

Harness مناسب می‌تواند استفاده مؤثرتری از توانایی مدل ایجاد کند؛ اما توانایی پایه مدل همچنان محدودیت دارد. بهترین نتیجه از انتخاب مدل مناسب همراه با Harness مناسب حاصل می‌شود.

آیا برای هر مدل به Harness جداگانه نیاز داریم؟

الزاماً نه. اگر لایه اتصال مدل به‌درستی جدا شده باشد، می‌توان Model ID یا Model Client را تغییر داد و بخش اصلی Harness را حفظ کرد. بااین‌حال، رفتار هر مدل باید با وظایف واقعی دوباره ارزیابی شود.

آیا API درواره برای Agentic Harness قابل‌استفاده است؟

بله. API درواره با استاندارد OpenAI سازگار است و می‌توان مدل‌های پشتیبانی‌شده را از طریق Base URL زیر به Harness متصل کرد:

https://api.darvareh.ir/v1

بهترین ابزار برای ساخت Agent Harness چیست؟

پاسخ به پیچیدگی پروژه بستگی دارد. برای Agent ساده، Python و یک حلقه Tool Calling کافی است. برای سیستم‌های پیچیده‌تر می‌توان LangChain، LangGraph، Deep Agents، LlamaIndex Workflows یا Google ADK را بررسی کرد.

مهم‌ترین بخش Agentic Harness چیست؟

هیچ جزء واحدی برای همه پروژه‌ها مهم‌ترین نیست؛ اما تعریف ابزار، مدیریت Context، حلقه اجرا، State و شرط توقف معمولاً بیشترین تأثیر را بر رفتار Agent دارند.

جمع‌بندی

Agentic Harness پلی میان توانایی خام مدل و انجام یک وظیفه واقعی است.

مدل می‌تواند درخواست را بفهمد، استدلال کند و اقدام بعدی را پیشنهاد دهد؛ اما Harness ابزارها را معرفی می‌کند، عملیات را اجرا می‌کند، نتیجه را به مدل بازمی‌گرداند و چرخه کار را تا رسیدن به پاسخ نهایی ادامه می‌دهد.

یک Harness مناسب شامل این اجزاست:

• Model Client
• System Instructions
• Tool Registry
• Agent Loop
• Context Manager
• State
• Memory
• Skillها
• اعتبارسنجی خروجی
• شرط توقف
• ارزیابی

اگر Agent شما عملکرد مناسبی ندارد، تنها مدل را بررسی نکنید. Prompt، تعریف ابزارها، Context، State و حلقه اجرا نیز می‌توانند علت اصلی باشند.

با استفاده از API درواره می‌توانید لایه مدل را از Harness جدا نگه دارید، چند مدل مختلف را با یک ساختار API آزمایش کنید و برای هر وظیفه، مدل مناسب‌تری انتخاب کنید.

درواره؛ دسترسی یکپارچه به مدل‌های هوش مصنوعی.

مقالات مرتبط

• AI Agent و Agent Skills چیست؟
• Context Engineering چیست؟
• Loop Engineering چیست؟
• Function Calling چیست؟
• MCP چیست؟
• Structured Outputs چیست؟
• AI Evals چیست؟
• API سازگار با OpenAI چیست؟
• اتوماسیون هوش مصنوعی چیست؟

منابع

• Anthropic: Demystifying Evals for AI Agents
• Anthropic: Effective Harnesses for Long-Running Agents
• Anthropic: Effective Context Engineering for AI Agents
• LangChain: Runtimes, Frameworks and Harnesses
• Databricks: What Is an AI Agent Harness?
• Google ADK: Sessions, State and Memory
• مستندات API سازگار با OpenAI درواره

این مقاله صرفاً با هدف آموزش و اطلاع‌رسانی تهیه شده است. پیش از استفاده عملی، مستندات رسمی سرویس‌ها و صفحه سلب مسئولیت را مطالعه کنید.