جمّع مهارات الوكلاء الموثوقة فآلات الحالات باستعمال HEXIS

شنو هو HEXIS؟

HEXIS هو حزمة Python وأداة سطر الأوامر كتجمّع مهارة ديال وكيل، ممثّلة فوثيقة SKILL.md، فآلة حالات منتهية موسّعة. بلاصة ما نطلبو من نموذج لغوي يفسّر المهارة كاملة ويختار كل خطوة جاية، كيستعمل HEXIS حالات ومتغيّرات وحواجز وانتقالات مبرمجة باش يفرض ترتيب العمليات.

النماذج اللغوية باقية كتدير الاستدلال والتوليد داخل الحالات المعنيّة. ولكن الآلة هي اللي كتحدّد شنو العملية اللي غادي تخدم من بعد، وشنو المتغيّرات المتاحة، وفاش خاص الحلقات توقف، وشنو النتيجة النهائية اللي غادي نوصلو ليها. هاد التصميم كيقلّل من خطر أن الوكيل يتجاوز أو يبدّل الترتيب أو يطبّق بشكل غلط المتطلبات المكتوبة فالمهارة.

HEXIS منشور برخصة MIT، وحاليا مصنّف كبرنامج ألفا. وهو مرافق للورقة Compiling Agent Skills into Extended Finite State Machines.

السيرورة الأساسية

السيرورة العادية ديال HEXIS فيها ثلاثة ديال المراحل:

1. التجميع: نموذج كيقرأ وثيقة المهارة، ومدخلات المهمة، وتعريفات الأدوات، وقواعد المهارة، ومن بعد كيصاوب مسودة ديال آلة efsm-v1. HEXIS كيتحقّق من المخطط، والحواجز، وقابلية الوصول، والإنهاء، وتغطية البنود، ومراجع الأدوات. المسودات غير الصالحة كيرجعها للنموذج باش يراجعها.
2. التحديث: آثار التنفيذ الجديدة كتتحوّل لأحداث موحّدة. فكل خطوة من الأثر، نموذج أو ملف قرارات أو أداة محاذاة حتمية كيقرّر واش يطابق حالة موجودة، ولا ينشئ حالة، ولا يتجاهل الضجيج، ولا يستبعد الأثر.
3. التنفيذ: وقت التشغيل كينفّذ الإجراء المرتبط بالحالة الحالية، وكي سجّل المخرجات المصرّح بها، وكياخذ أول انتقال اللي الحاجز ديالو كيقيّم بصحيح.

الآلة المحدّثة كتتقبل غير إلا دازت الفحوصات المطلوبة وقدرات تعاود تنفيذ الأثر الجديد وجميع الآثار اللي تقبلات من قبل. إلا فشل التحقّق، الآلة الموجودة كتبقى بلا تغيير.

المزايا الرئيسية

• تجميع متوافق مع OpenAI: اختار النموذج، ونقطة النهاية، ومتغيّر البيئة ديال مفتاح API من سطر الأوامر.
• تحديثات مبنية على الآثار: دمج سلوك التنفيذ الناجح قرار بقرار بلا ما تبطّل الآثار اللي تقبلات من قبل.
• آلات JSON مقروءة: الآلات كتستعمل صيغة JSON العادية efsm-v1 بمتغيّرات مبيّنة النوع وانتقالات واضحة.
• أنواع متعددة ديال الإجراءات: الحالات تقدر تنفّذ إجراءات tool أو model أو judge أو user أو end.
• تحكّم محدود فالتدفّق: الحواجز المرتّبة وعدادات الحلقات كيدعمو التفريع وحدود إعادة المحاولة.
• توثيق مولّد: كل عملية بناء عادية كتضمّن GUIDE.md وPROMPT.md.
• السلوك الاحتياطي: الحالة الاحتياطية كتعاود المحاولة من آخر خطوة ديال الأداة، وتقدر تسلّم المهمة لتنفيذ مفسَّر للمهارة الأصلية.
• واجهات الأدوات الخلفية: الآلات تقدر تستعمل أدوات OpenCode، أو منفّذ Bash محلي، أو أدوات معرّفة فالسجل وكيحقّقها نموذج.
• اختبارات معزولة: المستودع فيه أكثر من 350 اختبار ما كيحتاجوش مفتاح API ولا نقطة نهاية ديال نموذج ولا اتصال بالشبكة.

التثبيت والمتطلبات المسبقة

التثبيت من PyPI

HEXIS كيحتاج Python 3.11 ولا 3.12. ثبّت الحزمة باستعمال pip:

pip install hexis-agent

الحزمة كتستورد فـ Python باسم hexis، بينما الملف التنفيذي ديال سطر الأوامر سميتو hexis-agent.

التثبيت من نسخة مستخرجة

pip install .

بالنسبة لتبعيات التطوير بحال pytest وRuff وbuild وTwine، استعمل تثبيت قابل للتعديل:

pip install -e ".[dev]"

متطلبات وقت التشغيل

تجميع وتشغيل الآلات اللي كتستعمل النماذج كيحتاج نقطة نهاية للمحادثة متوافقة مع OpenAI. الواجهة الخلفية الافتراضية للتنفيذ كتتوقّع حتى OpenCode يكون موجود فـ PATH. إلا كانت الآلة محتاجة غير Bash، اختار --executor local باش تشغّل الأوامر فعملية فرعية محلية بلا OpenCode.

جرّب البداية السريعة بلا اتصال

الحزمة فيها مثال صغير ومعزول سميتو table_clean. كيستعمل نموذج مبرمج، وأدوات مبرمجة، ونظام ملفات فالذاكرة، وبهذا يقدر يخدم بلا اتصال بالشبكة.

from hexis.execution import runtime
from hexis.examples import table_clean as tc

machine = tc.reference_machine()
task = tc.gen_tasks(1, seed=0)[0]

result = runtime.run_task(
    machine,
    task,
    model=tc.build_model(),
    tools=tc.build_registry(tc.MemFS(task["files"])),
    doc=tc.skill_doc(),
)

print(
    result.stopped,
    " -> ".join(result.path()),
    tc.verify(task, result.trace),
)

خاص المثال يسالي بنتيجة نهائية، ويطبع مسار الحالات، ويبيّن واش الأثر الناتج داز من أداة التحقّق ديال المثال. هادي طريقة مفيدة باش تتأكّد أن التثبيت نجح قبل ما تهيّأ نقطة نهاية خارجية.

تهيئة نقطة نهاية نموذج

HEXIS كيقرأ معرّف النموذج، والرابط الأساسي، ومفتاح API من خيارات سطر الأوامر ولا من متغيّرات البيئة. إعداد أساسي فـ shell كيكون هكذا:

export API_KEY=your-key
export MODEL=qwen3.6-flash
export BASE_URL=https://your-endpoint/v1

وتقدر حتى تحط MODEL وBASE_URL وAPI_KEY فملف .env. HEXIS كيقلب للفوق انطلاقا من المجلد الحالي، والمتغيّرات الموجودة من قبل فالبيئة عندها الأولوية.

باش تخلي معاملات نقطة النهاية القابلة لإعادة الاستعمال فمتغيّر ديال shell:

M="--model qwen3.6-flash --base-url https://your-endpoint/v1"

الخيار --api-key-env NAME كيختار متغيّر بيئة مختلف للمفتاح. مفاتيح API ما كيتبعثوش فسطّر الأوامر وما كيتخزّنوش فبيان البناء.

كمپايل مهارة داخل آلة

وجّه الكمپايلر لمسار المهارة واختار مجلد الإخراج:

hexis-agent compile \
  --skill path/to/skill \
  --out build/ \
  $M

خاص مجلد المهارة يكون فيه SKILL.md. ويقدر حتى يكون فيه compile.json، اللي يقدر يصرّح بالنهائيات، وتسميات الأحداث المشتقة، والمتطلبات، وشروط النهاية. كل قاعدة فهاد الملف كتنقل الجملة اللي تشتقات منها.

إلا ما كانش compile.json، الكمپايلر كيطلب من الموديل يستخرج القواعد من المهارة وكيقارن النص المنقول مع الوثيقة. من بعد كيتحفظ الإعداد الفعّال فـ rules.json.

شنو كاين فمجلد البناء

• machine.json كيخزّن الآلة الحالية.
• machine_init.json كيحافظ على الآلة الأولية اللي تكمپايلات.
• build.json كيسجّل معلومات المصدر، وإعدادات الأمر، وتفاصيل الموديل، والنتائج، واستعمال التوكنات، ولكن عمره كيخزّن مفتاح API.
• skill/SKILL.md وtools.json وrules.json كيحافظو على مدخلات الكمپايل.
• traces/ فيه نسخ مَهَشّمة من التتبعات اللي تستعملات فالبناء.
• progress.json كيسجّل نتائج التتبعات والتتبعات المقبولة اللي كتحمي الآلة.
• decisions.jsonl كيخزّن أسئلة وأجوبة التحديث.
• report.md وcontext.json وملفات السجل كيعطيو معلومات تشخيصية.
• GUIDE.md كيشرح المدخلات، والأدوات، والحالات، والانتقالات، والحلقات، والسلوك الاحتياطي.
• PROMPT.md كيوفّر مطالبة نظام لوكيل كيستعمل الأدوات باش ينفّذ حالات الآلة وحدة بوحدة.

فهم نموذج الآلة

آلة HEXIS هي وثيقة JSON كتستعمل صيغة efsm-v1. العناصر الرئيسية ديالها هي المتغيّرات، والحالات، والإجراءات، والانتقالات، والنهائيات، وحالة احتياطية.

المتغيّرات

المتغيّرات يقدرو يتعيّنو من حقول مدخلات المهمة باستعمال init_from، ولا من قيم ثابتة باستعمال init. الإجراءات كيسجّلو النتائج ديالهم غير فالمتغيّرات المصرّح بها.

الإجراءات

• Model: كيولّد المتغيّرات المصرّح بها انطلاقاً من مطالبة خاصة بالحالة ومن متغيّرات الإدخال المختارة.
• Tool: كينادي على أداة مسمّاة. الإشارات بحال ${command} كتتعوّض وقت التشغيل.
• Judge: كيختار تسمية من مجموعة ثابتة ولا كيرجّع تسمية abstain.
• User: كيطلب إدخال من المستخدم.
• End: كيوقف التنفيذ بنتيجة نهائية.

الانتقالات والحراس

الانتقالات كتتقيّم بالترتيب من بعد ما كيسالي إجراء الحالة. وقت التشغيل كياخذ أول انتقال اللي الحارس ديالو متحقّق. الحارس الخاوي غير مشروط، وخصّو يبان فالآخر. الانتقال يقدر حتى يزيد عدّاد باستعمال inc، وهادشي كيمكن حلقات إعادة المحاولة المحدودة.

الحراس كيستعملو لغة تعابير محدودة كينفّذها hexis.machine.cond. كتدعم التحليل الساكن لخصائص بحال الاستبعاد المتبادل وحدود الحلقات، وما كتستعملش eval ديال Python.

تحديث آلة انطلاقاً من التتبعات

تتبعات التنفيذ هي ملفات JSON Lines. كيبداو ببيانات المهمة وحكم، ومن بعد كيجي حدث واحد فكل سطر. التتبّع يقدر يحتوي على نداءات الأدوات، ومخرجات الموديل، وحدث النهاية.

أولاً عاين التتبعات المعلّقة بلا نداءات للموديل وبلا كتابة تغييرات:

hexis-agent update \
  --build build/ \
  --traces traces/ \
  --show 3

ومن بعد دير التحديث:

hexis-agent update \
  --build build/ \
  --traces traces/ \
  $M

فكل خطوة من التتبّع، المقرّر كيختار نتيجة من أربع:

• match كيعيد استعمال حالة موجودة وكيزيد انتقال إلا كان ضروري.
• new كينشئ حالة على حساب الغرض المذكور.
• ignore كيحيد ضجيج الـ harness من الاعتبار.
• exclude كيستبعد التتبّع كامل.

جواب الموديل كيحدّد حتى حالة مرشّحة، وكيشرح الغرض من الخطوة، ويقدر يربطها ببند من المهارة. HEXIS كيتحقّق من الآلة المرشّحة الناتجة وكيعاود يشغّل جميع التتبعات المحمية قبل ما يقبلها.

استئناف التحديث والتحكّم فالتكاليف

أجوبة الموديل كتتخزّن فـ decisions.jsonl. إعادة نفس الأمر كتعاود تستعمل هاد الأجوبة، بينما التشغيل اللي تقطع بحالة خروج 3 يقدر يستأنف من التقدّم المحفوظ. استعمل --no-cache غير إلا كنت باغي عمداً الموديل يجاوب من جديد.

التحديث كيكلّف عموماً نداء واحد للموديل على كل خطوة من التتبّع. استعمل --max-traces N باش تحدّ من حجم التشغيل. وبالنسبة للبدائل بلا موديل، عطِ قرارات بشرية ولا خارجية عبر --decisions FILE، أو اختار المحاذاة الحتمية باستعمال --decider align.

قبل معالجة التتبعات الجديدة، HEXIS كيتحقّق من الآلة الحالية وكيعاود يشغّل كل تتبّع مقبول. إلا كان تعديل يدوي ولا تبديل فتعريف أداة خرّب البناء، الأمر كيخرج بحالة 2 بلا ما يبدّلو.

شغّل الآلة المكمپايلة

تفحّص build/GUIDE.md قبل التنفيذ. كيوثّق مدخلات المهمة المطلوبة، والأدوات المتاحة، وإجراءات الحالات، وترتيب الانتقالات، وحدود إعادة المحاولة، والسلوك الاحتياطي.

شغّل الآلة بمدخلات المهمة على شكل مفتاح-قيمة:

hexis-agent run \
  --machine build/ \
  --input request="Process this task" \
  --workdir work/ \
  --executor local \
  $M

زيد خيارات --input KEY=VALUE لكل مُدخل متوقَّع من الماكينة. باش تحفظ التنفيذ كأثر قابل لإعادة الاستعمال بصيغة JSON Lines، زيد:

--json run-trace.jsonl

المنفّذ الافتراضي كيستعمل أدوات OpenCode. المنفّذ المحلي كيشغّل أوامر Bash فعملية فرعية. وقت التشغيل، الماكينة تقدر تستعمل غير الأدوات اللي موفّرها الـ backend ديالها ولا المعرّفة فسجلّ الأدوات؛ HEXIS ما كيبدّلش الأدوات الناقصة بشكل صامت.

استعمل ماكينة من Python

نقطة الدخول الرئيسية لوقت التشغيل هي hexis.execution.runtime.run_task. عطيها ماكينة محمّلة، ومهمّة فيها كائن input، ومحوّل ديال النموذج، وسجلّ الأدوات، ووثيقة المهارة إلا كان التنفيذ الاحتياطي يقدر يحتاجها.

from hexis.execution import runtime

result = runtime.run_task(
    machine,
    {"input": {
        "request": "Answer the question",
        "output_path": "answer.txt",
    }},
    model=model,
    tools=tools,
    doc=skill_document,
)

print(result.stopped)
print(result.path())
print(result.trace)

من بين واجهات البرمجة المرتابطة كاينين hexis.machine.schema.load_machine لتحميل الماكينات، وhexis.llm.llm_client.client_from_env لإعداد نقطة النهاية، ودوال hexis.guide لرسم الأدلة والموجّهات ومخططات Mermaid.

خدم بالماكينات المثال الموفّرة

المستودع فيه ربعة ديال الماكينات المترجمة فـ examples/machines/:

• dabench: كيجيب على سؤال ديال تحليل البيانات على ملف بيانات باستعمال حساب.
• livemath: كيجيب على سؤال رياضي متعدد الاختيارات ومبني على مبرهنة.
• sealqa: كيجيب على سؤال من مجموعة محلية وكيضمّن الدليل.
• spreadsheet: كيعدّل مصنف بلا ما يبدّل البنية ديالو.

هاد الماكينات غالباً كتستعمل حالة ديال النموذج باش تكتب أمر shell، وحالة ديال الأداة باش تنفّذو، وإعادات محاولة محروسة مبنية على returncode، وخطوة ديال الأداة كتقرا الجواب من بعد، وحالة ديال الحكم كتختار بين طرف نهائي متحقَّق منو ولا غير متحقَّق منو.

مثلاً، شغّل ماكينة LiveMath بهاد الأمر:

hexis-agent run \
  --machine examples/machines/livemath \
  --input request="..." \
  --input output_path=answer.txt \
  --workdir work/ \
  --executor local \
  $M

الماكينات المثال يمكن تحميلها وفحص بنيتها بلا نموذج، ولكن تشغيلها كيتطلب نقطة نهاية ديال نموذج مهيّأة.

نصائح متقدمة

عاود ولّد التوثيق

الترجمة والتحديثات كينتجو التوثيق أوتوماتيكياً إلا استعملتي --no-guide. تقدر تعاود تولّدو يدوياً بهاد الأمر:

hexis-agent guide --build build/

وتقدر حتى تعطي الأمر مباشرة لـ machine.json. زيد --embed-skill إلا بغيتي موجّه الوكيل المولّد يضمّن المهارة الأصلية، باش يسمح بالتنفيذ المفسَّر من بعد الـ fallback.

وفّر تعريفات صريحة للأدوات

مرّر --tools registry.json ملي كتستعمل الماكينة أدوات مخصّصة. أسماء الأدوات كتتعامل معاها الترجمة كمعرّفات مبهمة. وقت التشغيل، الأدوات المعرّفة فالسجل تقدر تتحقّق كأوامر shell من طرف النموذج، بينما الأدوات الأصلية خاص الـ backend المختار يوفّرها.

ضبط طلبات النموذج

الترجمة والتحديثات كيدعمو خيارات بحال --temperature و--max-tokens و--llm-timeout و--llm-retries و--stream و--extra-body JSON. بالنسبة لنقاط النهاية المتوافقة مع Qwen، تقدر تتحكم فالتفكير وقت التشغيل باستعمال --no-think و--think-budget و--judge-think-budget.

استعمل متغيّرات البيئة الخاصة بالمزوّد

الخيار --provider NAME كيقرا NAME_MODEL وNAME_BASE_URL وNAME_API_KEY. كاينين قيم افتراضية مدمجة لأسماء المزوّدين MiniMax وDeepSeek.

عرف حالات الخروج

• 0 كيعني النجاح.
• 2 كيعني مشكل فطريقة الاستعمال أو الإعداد أو البناء.
• 3 كيعني فشل أو توقّف فـ نقطة نهاية النموذج؛ وكيتم حفظ التقدّم باش تقدر تكمل من بعد.

شغّل فحوصات التطوير

pytest
ruff check src tests
python -m build && twine check --strict dist/*

مجموعة الاختبارات معزولة. اختبارات OpenCode الخاصة كتتخطّى ملي ما كيكونش الملف التنفيذي opencode متوفّر.

الأمن والخصوصية

HEXIS يقدر ينفّذ معاملات الأدوات اللي كيولّدها النموذج اللغوي، بما فيها أوامر shell. شغّل أعباء العمل غير الموثوقة فبيئة معزولة، واستعمل غير الماكينات والمهارات والسجلات وملفات المهام اللي كتثق فيها.

عملية التحديث كترسل خطوات الأثر، ونتائج الأدوات المختصرة، وبنود المهارة لنقطة نهاية النموذج المهيّأة. مجلدات البناء كتحافظ على نسخ من الآثار وأسئلة النموذج. وزيد على هاد الشي، PROMPT.md فيه الماكينة كاملة والموجّهات المشتقة من المهارة. راجع هاد الملفات قبل ما تشاركها.

وقت التشغيل كيحدّ كل استدعاء للنموذج بموجّه الحالة اللي كيتنفّذ دابا، عوض ما يعرّض الماكينة كاملة لكل استدعاء.

الخلاصة

HEXIS كيحوّل تعليمات الوكلاء المكتوبة باللغة الطبيعية لسيرورات عمل واضحة ومتحقَّق منها. من خلال الجمع بين استدلال النموذج داخل الحالات والانتقالات البرمجية، وإعادة تشغيل الآثار، وإعادات المحاولة المحدودة، وقيود الأدوات، والأدلة المولّدة، والتعامل مع التنفيذ الاحتياطي، كيوفّر طريقة منظّمة باش يكون تنفيذ المهارات أكثر قابلية للتوقّع. بدا بالمثال اللي كيخدم بلا اتصال، وترجم مهارة صغيرة وموثوقة، وراجع الدليل المولّد، ومن بعد دخل الآثار بالتدريج مع مراقبة نتائج التحقّق.