HEXIS yordamida ishonchli agent ko‘nikmalarini holatlar avtomatlariga kompilyatsiya qilish

HEXIS nima?

HEXIS — SKILL.md hujjati bilan ifodalangan agent ko‘nikmasini kengaytirilgan chekli holatlar mashinasiga kompilyatsiya qiluvchi Python paketi va buyruq satri vositasi. Til modelidan butun ko‘nikmani talqin qilib, har bir keyingi qadamni tanlashni so‘rash o‘rniga, HEXIS amallar tartibini ta’minlash uchun dasturiy holatlar, o‘zgaruvchilar, qo‘riqchilar va o‘tishlardan foydalanadi.

Til modellari tegishli holatlar ichida fikrlash va generatsiyani bajarishda davom etadi. Biroq keyingi amalni qaysi biri bajarishini, qaysi o‘zgaruvchilar mavjudligini, sikllar qachon to‘xtashi va qaysi yakuniy natijaga erishilishini mashina belgilaydi. Ushbu dizayn agent ko‘nikmada yozilgan talablarni o‘tkazib yuborishi, tartibini o‘zgartirishi yoki noto‘g‘ri qo‘llashi xavfini kamaytiradi.

HEXIS MIT litsenziyasi ostida chiqarilgan va hozircha alfa dasturiy ta’minot sifatida belgilangan. U Compiling Agent Skills into Extended Finite State Machines maqolasiga hamroh sifatida taqdim etiladi.

Asosiy ish jarayoni

Odatdagi HEXIS ish jarayoni uch bosqichdan iborat:

1. Kompilyatsiya: Model ko‘nikma hujjati, topshiriq kiritmalari, vosita ta’riflari va ko‘nikma qoidalarini o‘qib, efsm-v1 mashinasining dastlabki variantini tayyorlaydi. HEXIS uning sxemasi, qo‘riqchilari, yetishuvchanligi, tugashi, bandlar qamrovi va vosita havolalarini tekshiradi. Noto‘g‘ri variantlar qayta ko‘rib chiqish uchun modelga yuboriladi.
2. Yangilash: Yangi bajarilish izlari hodisalarga normallashtiriladi. Har bir iz bosqichi uchun model, qarorlar fayli yoki deterministik moslashtirgich mavjud holatga moslashtirish, yangi holat yaratish, shovqinni e’tiborsiz qoldirish yoki izni chiqarib tashlash kerakligini belgilaydi.
3. Bajarish: Ishlash muhiti joriy holatga bog‘langan amalni bajaradi, e’lon qilingan chiqishlarni qayd etadi va qo‘riqchisi rost deb baholangan birinchi o‘tishdan foydalanadi.

Yangilangan mashina faqat kerakli tekshiruvlardan o‘tganda va yangi izni, shuningdek avval qabul qilingan barcha izlarni qayta bajara olganda qabul qilinadi. Tekshiruv muvaffaqiyatsiz bo‘lsa, mavjud mashina o‘zgarmaydi.

Asosiy imkoniyatlar

• OpenAI bilan mos kompilyatsiya: Buyruq satridan model, endpoint va API kaliti muhit o‘zgaruvchisini tanlang.
• Izlarga asoslangan yangilanishlar: Avval qabul qilingan izlarni yaroqsiz holga keltirmasdan, muvaffaqiyatli bajarilish xatti-harakatini bir vaqtning o‘zida bitta qaror orqali qo‘shing.
• O‘qilishi qulay JSON mashinalari: Mashinalar tiplashtirilgan o‘zgaruvchilar va aniq o‘tishlardan iborat oddiy JSON formatidagi efsm-v1 formatidan foydalanadi.
• Bir nechta amal turi: Holatlar tool, model, judge, user yoki end amallarini bajarishi mumkin.
• Chegaralangan boshqaruv oqimi: Tartiblangan qo‘riqchilar va sikl hisoblagichlari tarmoqlanish hamda qayta urinishlar chegaralarini qo‘llab-quvvatlaydi.
• Yaratilgan hujjatlar: Har bir oddiy yig‘ish jarayoni GUIDE.md va PROMPT.md fayllarini o‘z ichiga oladi.
• Zaxira xatti-harakat: Zaxira holati eng so‘nggi vosita bosqichidan qayta urinadi va topshiriqni original ko‘nikmaning talqin qilingan bajarilishiga topshirishi mumkin.
• Vosita backendlari: Mashinalar OpenCode vositalari, mahalliy Bash bajaruvchisi yoki model orqali amalga oshiriladigan reyestrda belgilangan vositalardan foydalanishi mumkin.
• Germetik testlash: Repozitoriyda API kaliti, model endpointi yoki tarmoq ulanishini talab qilmaydigan 350 dan ortiq test mavjud.

O‘rnatish va dastlabki talablar

PyPI’dan o‘rnatish

HEXIS Python 3.11 yoki 3.12 versiyasini talab qiladi. Paketni pip yordamida o‘rnating:

pip install hexis-agent

Paket Python’da hexis sifatida import qilinadi, buyruq satri bajariladigan fayli esa hexis-agent deb nomlanadi.

Checkout’dan o‘rnatish

pip install .

pytest, Ruff, build va Twine kabi ishlab chiqish bog‘liqliklari uchun tahrirlanadigan o‘rnatishdan foydalaning:

pip install -e ".[dev]"

Ishlash muhiti talablari

Modelga tayanuvchi mashinalarni kompilyatsiya qilish va ishga tushirish OpenAI bilan mos chat endpointini talab qiladi. Standart bajarish backendi, shuningdek, OpenCode dasturining PATHda bo‘lishini kutadi. Agar mashinaga faqat Bash kerak bo‘lsa, OpenCodesiz buyruqlarni mahalliy subprocessda ishga tushirish uchun --executor local parametrini tanlang.

Oflayn tezkor boshlashni sinab ko‘ring

Paket table_clean nomli kichik germetik misolni o‘z ichiga oladi. U skriptlangan model, skriptlangan vositalar va xotiradagi fayl tizimidan foydalanadi, shuning uchun tarmoqqa ulanmasdan ishlashi mumkin.

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),
)

Misol terminal natija bilan yakunlanishi, holatlar yo‘lini chiqarishi va yaratilgan iz misol tekshiruvchisidan o‘tgan-o‘tmaganini ko‘rsatishi kerak. Bu tashqi endpointni sozlashdan oldin o‘rnatish muvaffaqiyatli bo‘lganini tekshirishning foydali usulidir.

Model endpointini sozlash

HEXIS model identifikatori, asosiy URL va API kalitini buyruq satri parametrlaridan yoki muhit o‘zgaruvchilaridan o‘qiydi. Oddiy shell konfiguratsiyasi quyidagicha:

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

Shuningdek, MODEL, BASE_URL va API_KEY qiymatlarini .env fayliga joylashtirishingiz mumkin. HEXIS ishchi katalogdan yuqoriga qarab qidiradi va muhitda allaqachon mavjud bo‘lgan o‘zgaruvchilar ustuvor hisoblanadi.

Qayta foydalaniladigan endpoint argumentlarini shell o‘zgaruvchisida saqlash uchun:

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

--api-key-env NAME parametri kalit uchun boshqa muhit o‘zgaruvchisini tanlaydi. API kalitlari buyruq satrida uzatilmaydi va build manifestida saqlanmaydi.

Skillni mashinaga kompilyatsiya qilish

Kompilyatorga skill yo‘lini ko‘rsating va chiqish katalogini tanlang:

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

Skill katalogida SKILL.md bo‘lishi kerak. Unda terminallar, hosilaviy hodisa yorliqlari, talablar va terminal shartlarini e’lon qiluvchi compile.json fayli ham bo‘lishi mumkin. Ushbu fayldagi har bir qoida o‘zi hosil qilingan jumlani keltiradi.

Agar compile.json mavjud bo‘lmasa, kompilyator modeldan skilldan qoidalarni ajratib olishni so‘raydi va keltirilgan matnni hujjat bilan tekshiradi. Shundan so‘ng samarali konfiguratsiya rules.json sifatida saqlanadi.

Build katalogi tarkibi

• machine.json joriy mashinani saqlaydi.
• machine_init.json dastlabki kompilyatsiya qilingan mashinani saqlab qoladi.
• build.json manba ma’lumotlari, buyruq sozlamalari, model tafsilotlari, natijalar va token sarfini qayd etadi, ammo API kalitini hech qachon saqlamaydi.
• skill/SKILL.md, tools.json va rules.json kompilyatsiya kiritmalarini saqlab qoladi.
• traces/ buildda foydalanilgan izlarning xeshlangan nusxalarini o‘z ichiga oladi.
• progress.json iz natijalari va mashinani himoya qiluvchi qabul qilingan izlarni qayd etadi.
• decisions.jsonl yangilash savollari va javoblarini keshlaydi.
• report.md, context.json va log fayllari diagnostika ma’lumotlarini taqdim etadi.
• GUIDE.md kiritmalar, vositalar, holatlar, o‘tishlar, sikllar va zaxira xatti-harakatini tushuntiradi.
• PROMPT.md vositalardan foydalanuvchi agent uchun mashina holatini bosqichma-bosqich bajarishga mo‘ljallangan tizim promptini taqdim etadi.

Mashina modelini tushunish

HEXIS mashinasi efsm-v1 formatidan foydalanadigan JSON hujjatidir. Uning asosiy elementlari o‘zgaruvchilar, holatlar, amallar, o‘tishlar, terminallar va zaxira holatidan iborat.

O‘zgaruvchilar

O‘zgaruvchilar init_from yordamida topshiriq kiritmasi maydonlaridan yoki init yordamida doimiy qiymatlardan ishga tushirilishi mumkin. Amallar o‘z natijalarini faqat e’lon qilingan o‘zgaruvchilarga yozadi.

Amallar

• Model: Holatga xos prompt va tanlangan kiritma o‘zgaruvchilari asosida e’lon qilingan o‘zgaruvchilarni hosil qiladi.
• Tool: Nomlangan vositani chaqiradi. ${command} kabi havolalar ish vaqtida almashtiriladi.
• Judge: Belgilangan to‘plamdan yorliq tanlaydi yoki abstain yorlig‘ini qaytaradi.
• User: Foydalanuvchi kiritmasini so‘raydi.
• End: Bajarilishni terminal natija bilan to‘xtatadi.

O‘tishlar va guardlar

O‘tishlar holat amali tugagandan so‘ng tartib bilan baholanadi. Runtime guardi bajariladigan birinchi o‘tishni tanlaydi. Bo‘sh guard shartsiz hisoblanadi va oxirida joylashishi kerak. O‘tish inc orqali hisoblagichni ham oshirishi mumkin, bu chegaralangan qayta urinish sikllarini yoqadi.

Guardlar hexis.machine.cond tomonidan amalga oshiriladigan cheklangan ifodalar tilidan foydalanadi. U o‘zaro istisno va sikl chegaralari kabi xususiyatlarni statik tahlil qilishni qo‘llab-quvvatlaydi hamda Python’ning eval funksiyasidan foydalanmaydi.

Izlardan mashinani yangilash

Bajarilish izlari JSON Lines fayllaridir. Ular topshiriq metama’lumotlari va verdict bilan boshlanadi, keyin har bir satrda bittadan hodisa keladi. Iz vosita chaqiruvlari, model chiqishi va yakunlovchi hodisani o‘z ichiga olishi mumkin.

Avval model chaqiruvlarini amalga oshirmasdan yoki o‘zgarishlar yozmasdan kutilayotgan izlarni oldindan ko‘ring:

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

Keyin yangilashni bajaring:

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

Har bir iz bosqichi uchun qaror qabul qiluvchi to‘rtta natijadan birini tanlaydi:

• match mavjud holatni qayta ishlatadi va zarur bo‘lsa, o‘tish qo‘shadi.
• new ko‘rsatilgan maqsad asosida holat yaratadi.
• ignore harness shovqinini ko‘rib chiqishdan chiqaradi.
• exclude butun izni chiqarib tashlaydi.

Model javobi nomzod holatni ham aniqlaydi, bosqich maqsadini tavsiflaydi va uni skill bandi bilan bog‘lashi mumkin. HEXIS hosil bo‘lgan nomzod mashinasini tekshiradi va uni qabul qilishdan oldin barcha himoyalangan izlarni qayta ijro etadi.

Davom ettirish va yangilash xarajatlarini boshqarish

Model javoblari decisions.jsonl faylida keshlanadi. Xuddi shu buyruqni takrorlash ushbu javoblardan qayta foydalanadi, chiqish holati 3 bilan to‘xtatilgan ish esa saqlangan jarayondan davom ettirilishi mumkin. Modeldan ataylab qayta javob olishni istasangizgina --no-cache parametridan foydalaning.

Yangilash odatda har bir iz bosqichi uchun taxminan bitta model chaqiruvini talab qiladi. Ishlashni cheklash uchun --max-traces N parametridan foydalaning. Modelsiz muqobillar uchun inson yoki tashqi qarorlarni --decisions FILE orqali taqdim eting yoki --decider align yordamida deterministik moslashtirishni tanlang.

Yangi izlarni qayta ishlashdan oldin HEXIS joriy mashinani tekshiradi va qabul qilingan har bir izni qayta ijro etadi. Agar qo‘lda kiritilgan o‘zgarish yoki o‘zgartirilgan vosita ta’rifi buildni buzgan bo‘lsa, buyruq 2 holat kodi bilan chiqadi va uni o‘zgartirmaydi.

Kompilyatsiya qilingan mashinani ishga tushirish

Bajarishdan oldin build/GUIDE.md faylini ko‘rib chiqing. Unda talab qilinadigan topshiriq kiritmalari, mavjud vositalar, holat amallari, o‘tishlar tartibi, qayta urinish chegaralari va zaxira xatti-harakati hujjatlashtirilgan.

Mashinani kalit-qiymat ko‘rinishidagi topshiriq kiritmalari bilan ishga tushiring:

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

Mashina kutayotgan har bir kirish parametri uchun qo‘shimcha --input KEY=VALUE opsiyalarini uzating. Bajarilishni qayta foydalanish mumkin bo‘lgan JSON Lines izi sifatida saqlash uchun quyidagini qo‘shing:

--json run-trace.jsonl

Standart ijrochi OpenCode vositalaridan foydalanadi. Mahalliy ijrochi Bash buyruqlarini quyi jarayonda ishga tushiradi. Ishlash vaqtida mashina faqat o‘z backend’i taqdim etgan yoki vositalar reyestrida belgilangan vositalardan foydalanishi mumkin; HEXIS yetishmayotgan vositalarni sezdirmasdan almashtirmaydi.

Python’dan mashinadan foydalanish

Asosiy ishga tushirish nuqtasi hexis.execution.runtime.run_task hisoblanadi. Yuklangan mashina, input obyektiga ega topshiriq, model adapteri, vositalar reyestri va zaxira ijrosi uchun kerak bo‘lishi mumkin bo‘lgan ko‘nikma hujjatini uzating.

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)

Tegishli API’lar qatoriga mashinalarni yuklash uchun hexis.machine.schema.load_machine, endpoint konfiguratsiyasi uchun hexis.llm.llm_client.client_from_env hamda qo‘llanmalar, promptlar va Mermaid diagrammalarini yaratish uchun hexis.guide funksiyalari kiradi.

Taqdim etilgan namunaviy mashinalar bilan ishlash

Repozitoriyda examples/machines/ ostida to‘rtta kompilyatsiya qilingan mashina mavjud:

• dabench: Hisoblashdan foydalanib, ma’lumotlar fayli haqidagi tahliliy savolga javob beradi.
• livemath: Teoremaga asoslangan, bir nechta javob variantiga ega matematika savoliga javob beradi.
• sealqa: Mahalliy korpusdan olingan savolga dalillarni ham qo‘shgan holda javob beradi.
• spreadsheet: Tuzilmasini o‘zgartirmagan holda ish kitobini tahrirlaydi.

Bu mashinalar odatda qobiq buyrug‘ini yozish uchun model holatidan, uni bajarish uchun vosita holatidan, returncode asosidagi nazoratli qayta urinishlardan, javobni qayta o‘qiydigan vosita bosqichidan va tasdiqlangan yoki tasdiqlanmagan terminalni tanlaydigan hakam holatidan foydalanadi.

Masalan, LiveMath mashinasini quyidagicha ishga tushiring:

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

Namunaviy mashinalarni modelsiz yuklash va ularning tuzilmasini tekshirish mumkin, ammo ularni ishga tushirish uchun sozlangan model endpoint’i kerak.

Ilg‘or maslahatlar

Hujjatlarni qayta yaratish

Kompilyatsiya va yangilash jarayonlari --no-guide ishlatilmaganda hujjatlarni avtomatik yaratadi. Uni qo‘lda qayta yarating:

hexis-agent guide --build build/

Buyruqni bevosita machine.json fayliga ham yo‘naltirishingiz mumkin. Yaratilgan agent promptiga original ko‘nikmani qo‘shish va zaxira bajarilishidan keyin interpretatsiya qilingan ijroga ruxsat berish kerak bo‘lsa, --embed-skill opsiyasini qo‘shing.

Vositalarning aniq ta’riflarini taqdim etish

Mashina maxsus vositalardan foydalanganda --tools registry.json ni uzating. Kompilyatsiya vaqtida vosita nomlari shaffof bo‘lmagan identifikatorlar sifatida ko‘riladi. Ishlash vaqtida reyestrda belgilangan vositalar model tomonidan qobiq buyruqlari sifatida amalga oshirilishi mumkin, mahalliy vositalar esa tanlangan backend tomonidan taqdim etilishi kerak.

Model so‘rovlarini sozlash

Kompilyatsiya va yangilash jarayonlari --temperature, --max-tokens, --llm-timeout, --llm-retries, --stream va --extra-body JSON kabi opsiyalarni qo‘llab-quvvatlaydi. Qwen bilan mos endpoint’lar uchun ishlash vaqtidagi fikrlashni --no-think, --think-budget va --judge-think-budget orqali boshqarish mumkin.

Provayderga xos muhit o‘zgaruvchilaridan foydalanish

--provider NAME opsiyasi NAME_MODEL, NAME_BASE_URL va NAME_API_KEY qiymatlarini o‘qiydi. MiniMax va DeepSeek provayder nomlari uchun o‘rnatilgan standart qiymatlar mavjud.

Chiqish holatlarini bilish

• 0 muvaffaqiyatni bildiradi.
• 2 foydalanish, konfiguratsiya yoki kompilyatsiya muammosini bildiradi.
• 3 model endpoint’idagi nosozlik yoki uzilishni bildiradi; davom ettirish uchun jarayon saqlanadi.

Rivojlantirish tekshiruvlarini ishga tushirish

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

Testlar to‘plami tashqi muhitdan mustaqil. opencode bajariladigan fayli mavjud bo‘lmaganda, OpenCode’ga xos testlar o‘tkazib yuboriladi.

Xavfsizlik va maxfiylik

HEXIS til modellari yaratgan vosita argumentlarini, jumladan qobiq buyruqlarini bajarishi mumkin. Ishonchsiz ish yuklamalarini ajratilgan muhitda ishga tushiring va faqat o‘zingiz ishongan mashinalar, ko‘nikmalar, reyestrlar va topshiriq fayllaridan foydalaning.

Yangilash jarayoni iz bosqichlari, qisqartirilgan vosita natijalari va ko‘nikma bandlarini sozlangan model endpoint’iga yuboradi. Build kataloglarida iz nusxalari va model savollari saqlanadi. Bundan tashqari, PROMPT.md fayli ko‘nikmadan olingan to‘liq mashina va promptlarni o‘z ichiga oladi. Bu artefaktlarni ulashishdan oldin tekshiring.

Ishlash muhiti har bir model chaqiruvini butun mashinani har bir chaqiruvga oshkor qilish o‘rniga, ayni paytda bajarilayotgan holat prompti bilan cheklaydi.

Xulosa

HEXIS tabiiy tildagi agent ko‘rsatmalarini aniq va tasdiqlangan ish jarayonlariga aylantiradi. Holatlar ichidagi model fikrlashini dasturiy o‘tishlar, izlarni qayta ijro etish, chegaralangan qayta urinishlar, vosita cheklovlari, yaratiladigan qo‘llanmalar va zaxira ishlov berish bilan birlashtirib, ko‘nikmalarni bajarishni yanada bashorat qilinadigan qilishning tizimli usulini taqdim etadi. Oflayn namunadan boshlang, ishonchli kichik ko‘nikmani kompilyatsiya qiling, yaratilgan qo‘llanmani tekshiring, so‘ngra tasdiqlash natijalarini kuzatgan holda izlarni bosqichma-bosqich joriy qiling.