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

تصور کنید یک برنامه‌نویس بخواهد عاملی بسازد که بدون نظارت، کدهای پیچیده را در سرورهای شرکت تغییر دهد؛ در دنیای واقعی، این یعنی یک ریسک امنیتی عظیم. اما OpenHarness این معادله را تغییر می‌دهد تا مدل فقط «فکر کند» و یک لایه‌ی سخت‌گیرانه، «اجرا» را مدیریت کند.

طبق اعلام توسعه‌دهندگان این پروژه، فلسفه‌ی اصلی OpenHarness این است: «مدل، عامل است؛ اما کد، چارچوب (Harness) است». این رویکرد باعث می‌شود مدل زبانی بزرگ (LLM) — مثل کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن کتاب‌ها جواب می‌دهد — از لایه‌ی اجرای ابزارها جدا شود. با جداسازی مغز استدلالی از لایه‌ی اجرای ابزار، توسعه‌دهندگان می‌توانند مدل خود را بدون نیاز به بازنویسی کل سیستم مجوزها، حافظه و هماهنگی، تعویض کنند.

بسیاری از چارچوب‌های فعلی عوامل هوشمند، مدل را به عنوان مرکز جهان می‌بینند. در مقابل, OpenHarness با مدل به عنوان یک مؤلفه قابل تعویض (Pluggable Component) برخورد می‌کند. پیچیدگی واقعی — و جایی که قابلیت اطمینان شکست می‌خورد — در نحوه مدیریت اعتبارسنجی ابزارها، ردیابی هزینه‌ها و سرریز شدن بافت (Context Overflow) نهفته است. در اواخر سال ۲۰۲۴، تغییر رویکرد به سمت «گردش‌های کاری عامل‌محور» (Agentic Workflows) باعث شد تا این تفکیک معماری برای رسیدن به سطح استقرار تجاری و صنعتی حیاتی شود. این رویکرد یادآور تلاش‌های IBM در پروژه CUGA است که با ارائه یک چارچوب متن‌باز، پیوند ابزارهای محلی و پروتکل‌های ارتباطی را در عامل‌ها تسهیل کرد.

لایه‌ی ابزار و اجرا

به گزارش مستندات OpenHarness، این سیستم از یک دفتر ثبت ابزار (Tool Registry) ساختاریافته استفاده می‌کند. هر ابزار، مانند write_file یا run_python با یک طرح ورودی (Input Schema) دقیق تعریف شده است. برای این کار از dataclasses و یک کمکی سفارشی به نام fld برای توصیفات استفاده می‌شود. این ساختار تضمین می‌کند که LLM نتواند آرگومان‌های بدشکل یا مخرب را به یک تابع حساس سیستمی ارسال کند. فرآیند تبدیل راهنمای نوع پایتون (Python Type Hints) به JSON Schema از متد build_json_schema و تبدیل آرگومان‌های JSON خام به نمونه‌های ورودی تایپ‌شده از متد instantiate استفاده می‌کند.

برای اینکه چارچوب بتواند از داده‌های آزمایشی (Mock) به محیط تولید واقعی منتقل شود، از یک سیستم قدرتمند تبدیل نوع (Type-coercion) بهره می‌برد. مکانیزم _coerce انواع پیچیده پایتون را مدیریت کرده و مقادیر JSON خام را به str ،bool ،int ،float ،list یا dict تبدیل می‌کند، همان‌طور که توسط InputModel مورد نیاز است. این اعتبارسنجی سخت‌گیرانه از نفوذ خطاهای زمان اجرا به حلقه اصلی عامل جلوگیری می‌کند.

اجرا در این سیستم درون یک سیستم فایل مجازی (VirtualFS) رخ می‌دهد. VFS یک سندباکس (Sandbox) تعیین‌یافته و در حافظه (In-memory) ایجاد می‌کند. این محیط از حذف تصادفی فایل‌های میزبان توسط عامل‌ها جلوگیری کرده و در عین حال اجازه می‌دهد مدل کارهای پیچیده کدنویسی را شبیه‌سازی کند. این سیستم فایل مجازی متدهایی برای write (نوشتن)، read (خواندن)، exists (بررسی وجود)، list (لیست کردن فایل‌ها از طریق الگوهای glob) و یک نمای tree برای عیب‌یابی ارائه می‌دهد. در این لایه از fnmatch برای تطبیق الگوها و lstrip برای نرمال‌سازی مسیرها استفاده شده تا دسترسی به فایل‌ها پیش‌بینی‌پذیر و امن باقی بماند.

قابلیت‌های تفصیلی ابزارها

این سیستم مجموعه جامعی از ابزارهای پیش‌فرض را دارد که بر اساس هدف عملکردی دسته‌بندی شده‌اند:

• مدیریت فایل (File Manipulation):

  • write_file: ایجاد یا بازنویسی فایل‌ها با محتوای کامل. این ابزار تعداد بایت‌های نوشته شده را به عنوان بخشی از ToolResult ردیابی می‌کند.
  • read_file: بازیابی محتوای کامل یک فایل. اگر فایل وجود نداشته باشد، یک ToolResult با مقدار is_error=True بازمی‌گرداند.
  • edit: جایگزینی اولین occurrence از یک زیررشته (substring) قدیمی با یک رشته جدید در فایل هدف. این ابزار پیش از تلاش برای جایگزینی، اعتبارسنجی می‌کند که زیررشته مورد نظر وجود داشته باشد.

• تعامل با سیستم (System Interaction):

  • grep: جست‌وجوی محتویات فایل با استفاده از عبارات منظم (Regular Expressions) در یک الگوی glob. خروجی آن لیستی از یافته‌ها شامل مسیر فایل و شماره خط است (مثلاً path:line: content).
  • list_files: لیست کردن فایل‌هایی که با یک الگوی glob خاص مطابقت دارند (به طور پیش‌فرض *). نتایج به صورت یک رشته جدا شده با خط جدید بازگردانده می‌شوند.
  • shell: شبیه‌سازی دستورات شل. این ابزار دستورات ls ،cat و echo را به‌طور ویژه روی VFS مدیریت کرده و یک محیط شبیه‌سازی شده برای عملیات پایه CLI فراهم می‌کند.

• اجرا و تست (Execution and Testing):

  • run_python: اجرای کدهای پایتون از طریق ترکیب فایل‌های VFS و قطعات کد داخلی (inline snippets) در یک فضای نام (Namespace) واحد. این ابزار خروجی استاندارد (stdout) را از طریق io.StringIO دریافت کرده و ردپاهای (tracebacks) دقیق را با استفاده از traceback.extract_tb ارائه می‌دهد.
  • مدیریت خطا: اگر کرشی (crash) رخ دهد، سیستم دقیقاً خط کد در قطعه <agent_code> را شناسایی می‌کند تا به عامل در خود-اصلاحی (self-correction) کمک کند. این کار از طریق فیلتر کردن فریم‌هایی که f.filename == "<agent_code>" هستند انجام می‌شود.

• دانش و بستر (Knowledge and Context):

  • web_search: ابزاری شبیه‌سازی شده (Mocked) که پرس‌وجوهای وب را تقلید می‌کند. این ابزار از یک دیکشنری _FAKE_WEB برای بازگرداندن پاسخ‌های از پیش آماده برای عباراتی مثل «دیتابیس vektori»، «agent harness» یا «exponential backoff» استفاده می‌کند.
  • skill: بارگذاری پویا یک دفترچه راهنمای Markdown در پنجره متنی محدود. این ابزار نام و توضیحات را از بخش frontmatter (شبیه به YAML) استخراج می‌کند.
  • remember: ثبت یک حقیقت یا ترجیح بادوام در فایل بلندمدت MEMORY.md با استفاده از کلاس MemoryStore.
  • ask_user: ارسال یک سوال شفاف‌ساز برای کاربر انسانی، که در تست‌های خودکار دمو از یک دیکشنری canned_answers استفاده می‌کند.

• هماهنگی (Coordination):

  • spawn_agent: تفویض یک زیر-وظیفه به یک پروفایل عامل تخصصی (مثلاً «پژوهشگر») و بازگرداندن نتیجه نهایی. این قابلیت اجازه می‌دهد تا حلقه‌های تو در تو (Nested Loops) ایجاد شوند.

حکمرانی و مجوزهای دسترسی

امنیت در OpenHarness تک‌لایه نیست، بلکه یک دفاع لایه‌بندی شده است. مجوزها بر اساس PermissionKind دسته‌بندی می‌شوند که سیاست پیش‌فرض را هدایت می‌کند: READ (خواندن)، WRITE (نوشتن)، EXECUTE (اجرا) و META (متا).

بسته به پیکربندی، چارچوب تنظیمات مختلف PermissionMode را اعمال می‌کند:

• DEFAULT: عملیات استاندارد که برای اقدامات خطرناک نیاز به تأیید صریح دارد. این حالت جریان interactive_approve را فعال می‌کند که در آن کاربر باید با پاسخ y اجازه فراخوانی را بدهد.
• AUTO: تأیید خودکار برای تمامی ابزارها، که برای نمونه‌سازی سریع (Rapid Prototyping) استفاده می‌شود.
• PLAN: یک حالت محدودکننده که تمام اقدامات WRITE و EXECUTE را مسدود می‌کند و مدل را فقط به خواندن و استراتژی محدود می‌کند. در این حالت، ابزارهای READ و META به عنوان «ابزارهای امن» مجاز هستند.

فراتر از حالت‌ها، سیستم از یک PermissionChecker استفاده می‌کند که با الگوهای glob مسیرهای حساس را مسدود می‌کند. لیست SENSITIVE_PATTERNS شامل مسیرهای حیاتی مانند /etc/* ،*/.ssh/* ،*.pem ،*id_rsa* ،*/.aws/* ،*/secrets/* و */.env است.

توسعه‌دهندگان همچنین می‌توانند path_rules سفارشی (برای اجازه یا مسدود کردن دایرکتوری‌های خاص مانند build/*) و denied_commands (با استفاده از regex برای مسدود کردن دستوراتی مثل rm -rf / یا DROP TABLE) تعریف کنند. متدهای _check_path و _check_command این کنترل دقیق را پیش از ارسال هر ابزار فراهم می‌کنند.

علاوه بر این، یک HookManager به توسعه‌دهندگان اجازه می‌دهد منطق PreToolUse و PostToolUse را تزریق کنند. پیش‌قلاب‌ها (Pre-hooks) می‌توانند یک HookOutcome بازگردانند تا یا یک فراخوانی را کاملاً وتو کنند (مثلاً مسدود کردن write_file اگر محتوا شبیه رمز عبور باشد) یا آرگومان‌ها را قبل از رسیدن به ابزار تغییر دهند. پس-قلاب‌ها (Post-hooks) می‌توانند ToolResult را قبل از بازگشت به LLM رهگیری و سانسور کنند.

مدیریت حافظه و فشرده‌سازی پویا

برای حل مشکل رایج سرریز شدن پنجره متنی (Context Window Overflow)، OpenHarness قابلیت فشرده‌سازی خودکار (Auto-compaction) را پیاده‌سازی کرده است. وقتی یک گفتگو از یک آستانه توکن (تخمین زده شده حدود ۴ کاراکتر برای هر توکن) فراتر رود، تابع maybe_compact بخش میانی قدیمی‌تر متن گفتگو را خلاصه می‌کند.

نحوه عملکرد فشرده‌سازی:

• حفاظت (Preservation): وظیفه اصلی کاربر (اولین پیام) و جدیدترین نوبت‌های گفتگو (به طور پیش‌فرض keep_last=4) به طور کامل حفظ می‌شوند.
• خلاصه‌سازی (Summarization): پیام‌های «میانی» پردازش می‌شوند. نتایج ابزارهایی که خطا نداده‌اند و نوبت‌های دستیار با استفاده از کمکی short() به ۸۰ کاراکتر کاهش می‌یابند.
• تزریق (Injection): لیست حاصل از حقایق کلیدی در یک پیام واحد با نقش system و سرتیتر [Auto-compacted context] جمع می‌شود. این کار می‌تواند حجم متن را به‌طور قابل توجهی کاهش دهد (مثلاً از ۱۸ پیام به ۶ پیام).

این مکانیسم به عامل‌ها اجازه می‌دهد تا انسجام خود را در جلسات چندروزه بدون گم کردن هدف اصلی حفظ کنند. دانش همچنین از طریق یک کتابخانه مهارت (Skill Library) بر اساس نیاز مدیریت می‌شود. به جای گنجاندن هر دستورالعمل در پرامپت سیستمی، فقط نام‌ها و توصیفات مهارت‌ها از طریق متد summary() ارائه می‌شوند. در راستای استانداردسازی این نوع مدیریت داده‌ها، تلاش‌هایی برای ایجاد پروتکل‌های مشترک صورت گرفته است، مانند پروتکل UMP که قصد دارد وابستگی حافظه عامل‌ها به فروشندگان خاص را با استفاده از JSONهای قابل انتقال بشکند.

بارگذاری دانش مبتنی بر مهارت:

• پلی‌بوک‌های Markdown: مهارت‌ها به صورت فایل‌های markdown با frontmatter مدل YAML ذخیره می‌شوند که حاوی نام و شرح هستند.
• بارگذاری در لحظه (Just-in-Time): عامل از ابزار skill استفاده می‌کند تا بدنه کامل markdown را تنها زمانی که تخصص خاصی — مانند پلی‌بوک «commit» یا «review» — مورد نیاز است، بارگذاری کند.
• بهره‌وری: این روش از حجیم شدن پرامپت سیستمی جلوگیری کرده و در عین حال تخصص عمیق و قابل تعویضی را در اختیار عامل قرار می‌دهد.

وضعیت بلندمدت توسط یک MemoryStore دائمی که در فایل MEMORY.md می‌نویسد، مدیریت می‌شود. حقایقی که از طریق ابزار remember ثبت می‌شوند، بین جلسات باقی می‌مانند. هنگامی که یک نمونه جدید از موتور (Engine) مقداردهی اولیه می‌شود، این حافظه‌ها از دیسک خوانده شده و از طریق تابع assemble_system_prompt مستقیماً به پرامپت سیستمی تزریق می‌شوند. این اسمبلر پرامپت، دستورالعمل پایه سیستم، بافت پروژه (CLAUDE.md)، حافظه بلندمدت، لیست مهارت‌های در لحظه و نام ابزارهای موجود را با هم ترکیب می‌کند.

هماهنگی چندعاملی و منطق دسته‌ای

یکی از پیشرفته‌ترین ویژگی‌ها، توانایی ایجاد زیر-عامل‌های موازی (Parallel Subagents) است. در این معماری، یک «ابزار» در واقع می‌تواند یک چارچوب عامل کاملاً مجزا باشد که هر کدام مغز، دفتر ثبت و حلقه اجرای خود را دارد. این قابلیت با ارسال یک تابع spawn به ToolContext عامل پیاده‌سازی شده است.

در یک جریان هماهنگی معمولی، یک عامل ارشد (Lead Agent) یک وظیفه پیچیده را به زیر-وظایف تجزیه می‌کند. با استفاده از ابزار spawn_agent می‌تواند چندین نقش تخصصی را فعال کند. برای مثال، یک عامل ارشد می‌تواند دو «پژوهشگر» را به‌صورت موازی با استفاده از asyncio.gather اجرا کند. این زیر-عامل‌ها با مجموعه‌های ابزاری محدود خود (مثلاً فقط web_search) تعامل می‌کنند.

مثال از جریان هماهنگی:

• گام ۱: عامل ارشد نیاز به تحقیق درباره «دیتابیس‌های vektori» و «طراحی چارچوب عامل» را شناسایی می‌کند.
• گام ۲: دو زیر-عامل researcher ایجاد می‌شوند. هر کدام حلقه داخلی QueryEngine خود را اجرا می‌کنند و احتمالاً از مغز یا ابزارهای متفاوتی استفاده می‌کنند.
• گام ۳: یک عامل writer برای ترکیب یادداشت‌های پژوهشی جمع‌آوری شده در یک گزارش نهایی ایجاد می‌شود.
• گام ۴: عامل ارشد پاسخ نهایی را بر اساس خروجی نویسنده تولید می‌کند.
• ردیابی: یک دفتر ثبت تیمی تمام اجراهای زیر-عامل، شامل نقش، وظیفه محول شده و نتیجه نهایی را ردیابی می‌کند تا اجرای چندعاملی شفاف باشد.

این ساختار یک «سرمایه سلسله‌مراتبی» (Hierarchical Swarm) ایجاد می‌کند که قادر به مدیریت وظایف پیچیده تحقیق و ترکیب است؛ وظایفی که احتمالاً باعث سرریز شدن بافت در یک پرامپت واحد می‌شدند.

مغز قابل تعویض

از آنجا که چارچوب (Harness) تمامی جزئیات «چگونگی» — شامل مجوزها، قلاب‌ها، اجرا و ردیابی هزینه — را مدیریت می‌کند، «چیستی» (یعنی LLM) کاملاً قابل تعویض است. رابط LLMBrain تضمین می‌کند که QueryEngine نسبت به ارائه‌دهنده مدل agnostic (ناشناس/مستقل) باقی بماند.

OpenHarness چندین پیاده‌سازی مغز برای مراحل مختلف توسعه ارائه می‌دهد:

• ScriptedBrain: از لیستی از اقدامات پیش‌تعریف شده برای تست‌های قطعی و نمایش منطق‌های پیچیده مانند حلقه‌های اصلاح (fix-loops) استفاده می‌کند. این مغز، AssistantTurn یک LLM را با متن و فراخوانی ابزارها تقلید می‌کند.
• FlakyBrain: یک پوشش (Wrapper) است که خطاهای ارائه‌دهنده (مانند HTTP 503) را شبیه‌سازی می‌کند تا استقامت سیستم تست شود. این مغز تعداد مشخصی از دفعات (fail_times) شکست می‌خورد و سپس اجازه می‌دهد مغز داخلی ادامه دهد.
• RetryingBrain: عقب‌نشینی نمایی (delay = base_delay * 2^attempt) را برای بازیابی از استثنائات TransientLLMError پیاده‌سازی می‌کند. این کار از کرش کردن عامل به دلیل محدودیت‌های موقت Rate Limit در API جلوگیری می‌کند.
• RealLLMBrain: رابطی آماده برای تولید که از فرمت‌های Anthropic و OpenAI پشتیبانی می‌کند.

پیاده‌سازی‌های خاص هر مغز:

• فرمت Anthropic: از x-api-key و anthropic-version: 2023-06-01 استفاده می‌کند. ابزارها را به عنوان input_schema فرمت‌بندی کرده و بلوک‌های tool_use را در لیستی از بلوک‌های محتوا مدیریت می‌کند.
• فرمت OpenAI: از Authorization: Bearer استفاده کرده و ابزارها را به عنوان اشیاء function با parameters فرمت می‌کند. فراخوانی‌های ابزار (tool_calls) را به عنوان بخشی از شیء پیام هندل می‌کند.
• منطق شبکه: هر دو از urllib.request در محیط loop.run_in_executor استفاده می‌کنند تا از مسدود شدن حلقه async جلوگیری شود. آن‌ها کدهای HTTP 429، 500، 502، 503 و 504 را به عنوان TransientLLMError در نظر می‌گیرند.

RealLLMBrain به توسعه‌دهنده اجازه می‌دهد تا تنها با تغییر یک متغیر محیطی (USE_REAL_LLM=1)، بین یک مدل محلی Llama از طریق Ollama و یک نمونه Claude 3.5 Sonnet سطح بالا جابجا شود، بدون اینکه حتی یک خط از تعریف ابزارها یا منطق هماهنگی تغییر کند.

پایش عملیاتی و هزینه‌ها

برای مدیریت هزینه‌های تولید و قابلیت اطمینان، OpenHarness شامل یک CostMeter داخلی است. این ابزار از یک «دفتر قیمت‌ها» (PRICE_BOOK) استفاده می‌کند تا هزینه‌های دلاری را بر اساس توکن‌های ورودی و خروجی برای مدل‌های مختلف تخمین بزند.

مثال‌هایی از دفتر قیمت‌ها:

• mock-sonnet / claude-sonnet-4: ۳.۰۰ دلار (ورودی) / ۱۵.۰۰ دلار (خروجی) به ازای هر میلیون توکن.
• gpt-4.1: ۲.۰۰ دلار (ورودی) / ۸.۰۰ دلار (خروجی) به ازای هر میلیون توکن.
• default: ۱.۰۰ دلار (ورودی) / ۳.۰۰ دلار (خروجی) به ازای هر میلیون توکن.

این هزینه بعد از هر نوبت پاسخ دستیار از طریق کلاس Usage به‌روزرسانی می‌شود و خلاصه لحظه‌ای از تأثیر مالی حلقه استدلالی عامل را (ترکیبی از کل توکن‌ها و تعداد کل فراخوانی‌های مدل) ارائه می‌دهد. خلاصه‌های CostMeter به این شکل هستند: X model call(s) | in=Y out=Z tok | ~$W (model).

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

گام بعدی شما

• برای شروع، یک طرح ورودی (Input Schema) سخت‌گیرانه برای ابزارهای حساس پروژه خود تعریف کنید.
• محیط اجرای مدل‌های خود را با یک سیستم فایل مجازی (Virtual FS) ایزوله کنید تا ریسک دسترسی به فایل‌های سیستم حذف شود.
• از متد spawn_agent برای تقسیم وظایف پیچیده بین چندین مدل کوچک‌تر و ارزان‌تر استفاده کنید.

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