Hlanganisa Amakhono E-ejenti Athembekile Abe Imishini Yezimo nge-HEXIS

Yini i-HEXIS?

I-HEXIS iyiphakheji ye-Python kanye nethuluzi lomugqa womyalo elihlanganisa ikhono le-ejenti, elimelelwa idokhumenti ye-SKILL.md, libe umshini wezimo ophelele onwetshiwe. Esikhundleni sokucela imodeli yolimi ukuthi ihumushe lonke ikhono bese ikhetha isinyathelo ngasinye esilandelayo, i-HEXIS isebenzisa izimo zohlelo, okuguquguqukayo, iziqaphi, kanye nezinguquko ukuze iphoqelele ukulandelana kwemisebenzi.

Amamodeli olimi asaqhubeka nokwenza ukucabanga nokukhiqiza ngaphakathi kwezimo ezifanele. Nokho, umshini unquma ukuthi yimuphi umsebenzi ozosebenza ngokulandelayo, ukuthi yiziphi izinguquko ezitholakalayo, ukuthi amaluphu kufanele ame nini, nokuthi yimuphi umphumela wokugcina ofinyelelwayo. Lo mklamo unciphisa ubungozi bokuthi i-ejenti yeqe, iguqule ukulandelana, noma isebenzise ngokungafanele izimfuneko ezibhalwe ekhono.

I-HEXIS ikhishwa ngaphansi kwelayisensi ye-MIT futhi okwamanje imakwe njengesoftware ye-alpha. Ihambisana nephepha elithi Compiling Agent Skills into Extended Finite State Machines.

Ukuhamba komsebenzi okuyisisekelo

Ukuhamba komsebenzi okujwayelekile kwe-HEXIS kunezigaba ezintathu:

1. Hlanganisa: Imodeli ifunda idokhumenti yekhono, okokufaka komsebenzi, izincazelo zamathuluzi, kanye nemithetho yekhono, bese ibhala uhlaka lomshini we-efsm-v1. I-HEXIS ihlola i-schema sawo, iziqaphi, ukufinyeleleka kwezimo, ukuqedwa, ukumbozwa kwezigatshana, kanye nezinkomba zamathuluzi. Imidwebo engavumelekile ibuyiselwa kumodeli ukuze ibuyekezwe.
2. Buyekeza: Imikhondo emisha yokwenza iguqulwa ibe yimicimbi. Esinyathelweni ngasinye somkhondo, imodeli, ifayela lezinqumo, noma isihlanganisi esinqumayo sinquma ukuthi kufanele kufaniswe nesimo esikhona, kudalwe isimo, kunganakwa umsindo, noma kukhishwe umkhondo.
3. Yenza: Isikhathi sokusebenza senza isenzo esihlotshaniswa nesimo samanje, sirekhode okukhiphayo okumenyezelwe, bese sithatha uguquko lokuqala olunomqaphi ohlola abe yiqiniso.

Umshini obuyekeziwe wamukelwa kuphela uma uphumelela ekuhlolweni okudingekayo futhi ukwazi ukudlala kabusha umkhondo omusha kanye nayo yonke imikhondo eyamukelwe ngaphambilini. Uma ukuqinisekiswa kwehluleka, umshini okhona uhlala ungashintshiwe.

Izici ezibalulekile

• Ukuhlanganisa okuhambisana ne-OpenAI: Khetha imodeli, indawo yokugcina, kanye nokuguquguquka kwemvelo kokhiye we-API emugqeni womyalo.
• Izibuyekezo ezisekelwe emikhondweni: Faka ukuziphatha kokwenza okuphumelele, isinqumo esisodwa ngesikhathi, ngaphandle kokwenza imikhondo eyamukelwe ngaphambilini ingasebenzi.
• Imishini ye-JSON efundekayo: Imishini isebenzisa ifomethi ecacile ye-JSON ye-efsm-v1 eneziguquko ezinezinhlobo nezinguquko ezicacile.
• Izinhlobo eziningi zezenzo: Izimo zingenza izenzo ze-tool, model, judge, user, noma end.
• Ukugeleza kokulawula okunomkhawulo: Iziqaphi ezihlelwe ngokulandelana nezibali zamaluphu zisekela ukuhlukanisa izindlela nemikhawulo yokuzama futhi.
• Imibhalo ekhiqizwayo: Ukwakha okujwayelekile ngakunye kuhlanganisa i-GUIDE.md ne-PROMPT.md.
• Ukuziphatha kokubuyela emuva: Isimo sokubuyela emuva siqala futhi esinyathelweni sethuluzi sakamuva futhi singadlulisela umsebenzi ekwenzeni okuhunyushiwe kwekhono lokuqala.
• Ama-backend wamathuluzi: Imishini ingasebenzisa amathuluzi e-OpenCode, umenzi we-Bash wasendaweni, noma amathuluzi achazwe kurejista enziwa yimodeli.
• Ukuhlola oku-hermetic: Indawo yokugcina inezivivinyo ezingaphezu kuka-350 ezingadingi ukhiye we-API, indawo yokugcina yemodeli, noma uxhumano lwenethiwekhi.

Ukufakwa nezimfuneko zangaphambili

Faka ku-PyPI

I-HEXIS idinga i-Python 3.11 noma 3.12. Faka iphakheji nge-pip:

pip install hexis-agent

Iphakheji ingeniswa ku-Python njenge-hexis, kanti okusebenzisekayo komugqa womyalo kubizwa ngokuthi hexis-agent.

Faka usuka endaweni ekhokhiwe

pip install .

Ukuze uthole izincike zokuthuthukisa ezifana ne-pytest, i-Ruff, i-build, ne-Twine, sebenzisa ukufakwa okuhlelekayo:

pip install -e ".[dev]"

Izimfuneko zesikhathi sokusebenza

Ukuhlanganisa nokusebenzisa imishini esekelwe kumamodeli kudinga indawo yokugcina yengxoxo ehambisana ne-OpenAI. I-backend ezenzakalelayo yokwenza iphinde ilindele i-OpenCode ibe ku-PATH. Uma umshini udinga i-Bash kuphela, khetha --executor local ukuze wenze imiyalo ku-subprocess yasendaweni ngaphandle kwe-OpenCode.

Zama ukuqala ngokushesha ungaxhunyiwe ku-inthanethi

Iphakheji ihlanganisa isibonelo esincane se-hermetic esibizwa ngokuthi table_clean. Sisebenzisa imodeli ebhalwe kusengaphambili, amathuluzi abhalwe kusengaphambili, kanye nesistimu yamafayela egcinwa enkumbulweni, ngakho singasebenza ngaphandle kokufinyelela kunethiwekhi.

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

Isibonelo kufanele siqede ngomphumela wokugcina, siphrinte indlela yezimo, futhi sibike ukuthi umkhondo okhiqiziwe uyaphumelela yini kumqinisekisi wesibonelo. Lena yindlela ewusizo yokuqinisekisa ukuthi ukufakwa kuphumelele ngaphambi kokulungiselela indawo yokugcina yangaphandle.

Lungiselela indawo yokugcina yemodeli

I-HEXIS ifunda isihlonzi semodeli, i-URL eyisisekelo, kanye nokhiye we-API ezinkethweni zomugqa womyalo noma eziguquguqukayo zemvelo. Ukulungiselela okuyisisekelo kwe-shell kubukeka kanje:

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

Ungakwazi futhi ukufaka i-MODEL, i-BASE_URL, kanye ne-API_KEY kufayela le-.env. I-HEXIS isesha ikhuphukela phezulu isuka kuhla lokusebenza, futhi izinguquguquko ezivele zikhona emvelweni ziza kuqala.

Ukuze ugcine izimpikiswano zendawo yokugcina ezisebenziseka kabusha ekuguquguqukeni kwe-shell:

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

Inketho ethi --api-key-env NAME ikhetha enye i-environment variable yokugcina ukhiye. Okhiye be-API abadluliswa kulayini womyalo futhi abagcinwa ku-build manifest.

Hlanganisa i-skill ibe umshini

Qondisa i-compiler endleleni ye-skill bese ukhetha ifolda yokuphumayo:

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

Ifolda ye-skill kufanele ibe ne-SKILL.md. Ingase futhi ibe ne-compile.json, engachaza ama-terminal, amalebula emicimbi atholakele, izimfuneko, kanye nemibandela yama-terminal. Umthetho ngamunye kulelo fayela ucaphuna umusho owathathwa kuwo.

Uma i-compile.json ingekho, i-compiler icela imodeli ukuthi ikhiphe imithetho ku-skill bese ihlola umbhalo ocashuniwe iqhathanisa nedokhumenti. I-configuration esebenzayo ibe isigcinwa njenge-rules.json.

Okuqukethwe yifolda ye-build

• machine.json igcina umshini wamanje.
• machine_init.json igcina umshini wokuqala owahlanganiswa.
• build.json igcina ulwazi lomthombo, izilungiselelo zomyalo, imininingwane yemodeli, imiphumela, nokusetshenziswa kwama-token, kodwa ayilokothi igcine ukhiye we-API.
• skill/SKILL.md, tools.json, kanye ne-rules.json kugcina okokufaka kokuhlanganisa.
• traces/ iqukethe amakhophi anama-hash ama-trace asetshenziswe yi-build.
• progress.json igcina imiphumela yama-trace kanye nama-trace amukelwe avikela umshini.
• decisions.jsonl igcina imibuzo nezimpendulo zokubuyekeza.
• report.md, context.json, kanye namafayela e-log kunikeza ulwazi lokuxilonga.
• GUIDE.md ichaza okokufaka, amathuluzi, izimo, izinguquko, ama-loop, kanye nokuziphatha kwe-fallback.
• PROMPT.md inikeza i-system prompt ye-agent esebenzisa amathuluzi ukuze yenze umshini isimo ngesimo.

Qonda imodeli yomshini

Umshini we-HEXIS uyidokhumenti ye-JSON esebenzisa ifomethi ethi efsm-v1. Izinto zawo eziyinhloko yiziguquguquki, izimo, izenzo, izinguquko, ama-terminal, kanye nesimo se-fallback.

Iziguquguquki

Iziguquguquki zingaqaliswa zisuka ezinkambeni zokokufaka komsebenzi nge-init_from, noma zisuka kumanani angaguquki nge-init. Izenzo zibhala imiphumela yazo kuphela eziguquguqukini ezichaziwe.

Izenzo

• Model: Ikhiqiza iziguquguquki ezichaziwe isebenzisa i-prompt eqondene nesimo kanye neziguquguquki zokokufaka ezikhethiwe.
• Tool: Ibiza ithuluzi eliqanjwe igama. Izinkomba ezifana ne-${command} ziyashintshwa ngesikhathi sokusebenza.
• Judge: Ikhetha ilebula eqoqweni elimisiwe noma ibuyise ilebula ethi abstain.
• User: Icela okokufaka kumsebenzisi.
• End: Imisa ukusebenza ngomphumela we-terminal.

Izinguquko nama-guard

Izinguquko zihlolwa ngokulandelana ngemva kokuba isenzo sesimo siqedile. I-runtime ithatha ushintsho lokuqala olune-guard efezekayo. I-guard engenalutho ayinambandela futhi kufanele ivele ekugcineni. Ushintsho lungaphinde lwandise i-counter nge-inc, okwenza kube nokwenzeka ama-loop okuzama futhi anomkhawulo.

Ama-guard asebenzisa ulimi lwezisho olukhawulelwe olusetshenziswa yi-hexis.machine.cond. Lusekela ukuhlaziywa okumile kwezici ezifana nokungakhethi ndawonye kanye nemingcele yama-loop, futhi alusebenzisi i-eval ye-Python.

Buyekeza umshini usebenzisa ama-trace

Ama-trace okusebenza angamafayela e-JSON Lines. Aqala ngemininingwane yomsebenzi kanye nesinqumo, kulandelwe umcimbi owodwa emugqeni ngamunye. I-trace ingaqukatha ukubizwa kwamathuluzi, okukhiphayo kwemodeli, kanye nomcimbi wokuphetha.

Qala ngokubuka kuqala ama-trace asalindile ngaphandle kokwenza izingcingo zemodeli noma ukubhala izinguquko:

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

Bese wenza ukubuyekeza:

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

Ngesinyathelo ngasinye se-trace, i-decider ikhetha omunye wemiphumela emine:

• match iphinda isebenzise isimo esikhona futhi yengeze ushintsho uma kudingeka.
• new idala isimo esisekelwe enjongweni eshiwo.
• ignore isusa umsindo we-harness ekucatshangelweni.
• exclude ikhipha yonke i-trace.

Impendulo yemodeli iphinde ikhombe isimo esingase sisetshenziswe, ichaze inhloso yesinyathelo, futhi ingayihlanganisa nesigaba se-skill. I-HEXIS iqinisekisa umshini ovelayo bese iphinda idlale wonke ama-trace avikelwe ngaphambi kokuwamukela.

Qhubeka futhi ulawule izindleko zokubuyekeza

Izimpendulo zemodeli zigcinwa ku-decisions.jsonl. Ukuphinda usebenzise umyalo ofanayo kuphinda kusebenzise lezo zimpendulo, kanti ukusebenza okuphazamisekile okunekhodi yokuphuma engu-3 kungaqhubeka kusukela enqubekelaphambili egciniwe. Sebenzisa i---no-cache kuphela uma uhlose ukuthi imodeli iphendule futhi.

Ngokuvamile ukubuyekeza kubiza cishe ucingo olulodwa lwemodeli ngesinyathelo ngasinye se-trace. Sebenzisa i---max-traces N ukukhawulela ukusebenza. Ngezinye izindlela ezingadingi imodeli, nikeza izinqumo zomuntu noma zangaphandle nge---decisions FILE, noma ukhethe ukuvumelanisa okunqunywe kusengaphambili nge---decider align.

Ngaphambi kokucubungula ama-trace amasha, i-HEXIS ihlola umshini wamanje bese iphinda idlale wonke ama-trace amukelwe. Uma ukuhlela ngesandla noma incazelo yethuluzi eshintshiwe konakalise i-build, umyalo uphuma ngesimo 2 ngaphandle kokuyishintsha.

Qalisa umshini ohlanganisiwe

Hlola i-build/GUIDE.md ngaphambi kokusebenza. Ichaza okokufaka komsebenzi okudingekayo, amathuluzi atholakalayo, izenzo zezigaba, ukuhleleka kwezinguquko, imikhawulo yokuzama futhi, kanye nokuziphatha kwe-fallback.

Qalisa umshini usebenzisa okokufaka komsebenzi okuyizibhangqa zokhiye nenani:

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

Dlulisa izinketho ezengeziwe ze---input KEY=VALUE kukho konke okokufaka okulindelwe umshini. Ukuze ulondoloze ukusebenza njenge-trace eseb再benzisekayo ye-JSON Lines, engeza:

--json run-trace.jsonl

Umsebenzisi ozenzakalelayo usebenzisa amathuluzi e-OpenCode. Umsebenzisi wendawo usebenzisa imiyalo ye-Bash ku-subprocess. Ngesikhathi sokusebenza, umshini ungasebenzisa kuphela amathuluzi anikezwe yi-backend yawo noma achazwe kurejista yamathuluzi; i-HEXIS ayishintshi buthule amathuluzi angekho.

Sebenzisa umshini usuka ku-Python

Indawo eyinhloko yokungena ku-runtime yi-hexis.execution.runtime.run_task. Nikeza umshini olayishiwe, umsebenzi one-objekthi ye-input, i-adapter yemodeli, irejista yamathuluzi, kanye nedokhumenti ye-skill lapho ukubuyela ekusebenzeni kungase kuyidinge.

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)

Ama-API ahlobene afaka i-hexis.machine.schema.load_machine yokulayisha imishini, i-hexis.llm.llm_client.client_from_env yokulungisa i-endpoint, kanye nemisebenzi ye-hexis.guide yokukhiqiza imihlahlandlela, ama-prompt, nemidwebo ye-Mermaid.

Sebenza ngemishini eyisibonelo enikeziwe

Inqolobane ihlanganisa imishini emine ehlanganisiwe ngaphansi kwe-examples/machines/:

• dabench: Iphendula umbuzo wokuhlaziya idatha mayelana nefayela ledatha isebenzisa ukubala.
• livemath: Iphendula umbuzo wezibalo onezinketho eziningi osekelwe ku-theorem.
• sealqa: Iphendula umbuzo ovela ku-corpus yendawo futhi ifake nobufakazi.
• spreadsheet: Ihlela i-workbook ngaphandle kokushintsha isakhiwo sayo.

Le mishini ivame ukusebenzisa isimo semodeli ukubhala umyalo we-shell, isimo sethuluzi ukuwusebenzisa, ukuzama kabusha okulawulwayo okusekelwe ku-returncode, isinyathelo sethuluzi esifunda impendulo futhi, kanye nesimo sejaji esikhetha i-terminal eqinisekisiwe noma engakaqinisekiswa.

Ngokwesibonelo, sebenzisa umshini we-LiveMath kanje:

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

Imishini eyisibonelo ingalayishwa futhi ihlolwe ngokwesakhiwo ngaphandle kwemodeli, kodwa ukuyisebenzisa kudinga i-endpoint yemodeli elungiselelwe.

Amathiphu athuthukile

Phinda ukhiqize imibhalo

Ukuhlanganisa nokubuyekeza kukhiqiza imibhalo ngokuzenzakalelayo ngaphandle kokuthi kusetshenziswe i---no-guide. Yikhiqize kabusha mathupha ngale ndlela:

hexis-agent guide --build build/

Ungakhomba futhi umyalo ngqo ku-machine.json. Engeza i---embed-skill uma ufuna i-agent prompt ekhiqiziwe ifake i-skill yoqobo, okuvumela ukusebenza okuhunyushiwe ngemva kokubuyela emuva.

Nikeza izincazelo zamathuluzi ezicacile

Dlulisa i---tools registry.json lapho umshini usebenzisa amathuluzi angokwezifiso. Amagama amathuluzi aphathwa njengezihlonzi ezingabonakali ngesikhathi sokuhlanganisa. Ngesikhathi sokusebenza, amathuluzi achazwe kurejista angenziwa abe imiyalo ye-shell yimodeli, kanti amathuluzi omdabu kufanele anikezwe yi-backend ekhethiwe.

Lungisa izicelo zemodeli

Ukuhlanganisa nokubuyekeza kusekela izinketho ezihlanganisa i---temperature, --max-tokens, --llm-timeout, --llm-retries, --stream, kanye ne---extra-body JSON. Kuma-endpoint ahambisana ne-Qwen, ukucabanga kwe-runtime kungalawulwa nge---no-think, --think-budget, kanye ne---judge-think-budget.

Sebenzisa okuguquguqukayo kwemvelo okuqondene nomhlinzeki

Inketho ye---provider NAME ifunda i-NAME_MODEL, NAME_BASE_URL, kanye ne-NAME_API_KEY. Izilungiselelo ezizenzakalelayo ezakhelwe ngaphakathi ziyatholakala kumagama abahlinzeki i-MiniMax ne-DeepSeek.

Yazi izimo zokuphuma

• 0 ikhombisa impumelelo.
• 2 ikhombisa inkinga yokusetshenziswa, yokumisa, noma yokwakha.
• 3 ikhombisa ukwehluleka noma ukuphazamiseka kwe-endpoint yemodeli; inqubekelaphambili iyalondolozwa ukuze kuqhutshwe futhi.

Qalisa ukuhlola kokuthuthukisa

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

Isethi yokuhlola ayincikile ezintweni zangaphandle. Ukuhlola okuqondene ne-OpenCode kweqiwa lapho i-executable ye-opencode ingatholakali.

Ukuphepha nobumfihlo

I-HEXIS ingasebenzisa ama-argument amathuluzi akhiqizwe amamodeli olimi, kuhlanganise nemiyalo ye-shell. Sebenzisa imithwalo yomsebenzi ongathembekile endaweni ehlukanisiwe, futhi usebenzise kuphela imishini, ama-skill, amarejista, namafayela emisebenzi owathembayo.

Inqubo yokubuyekeza ithumela izinyathelo ze-trace, imiphumela yamathuluzi efinyezwe, kanye nezigaba ze-skill ku-endpoint yemodeli emisiwe. Izinkomba zokwakha zigcina amakhophi e-trace nemibuzo yemodeli. Ngaphezu kwalokho, i-PROMPT.md iqukethe umshini ophelele nama-prompt athathwe ku-skill. Buyekeza lezi zinto ngaphambi kokwabelana ngazo.

I-runtime ikhawulela ucingo ngalunye lwemodeli ku-prompt yesimo esisebenzayo njengamanje, esikhundleni sokudalula wonke umshini ocingweni ngalunye.

Isiphetho

I-HEXIS iguqula imiyalelo yama-agent ebhalwe ngolimi lwemvelo ibe ukugeleza komsebenzi okucacile nokuqinisekisiwe. Ngokuhlanganisa ukucabanga kwemodeli ngaphakathi kwezimo nezinguquko ezilawulwa wuhlelo, ukudlalwa kabusha kwama-trace, ukuzama kabusha okulinganiselwe, imikhawulo yamathuluzi, imihlahlandlela ekhiqiziwe, nokusingathwa kokubuyela emuva, inikeza indlela ehlelekile yokwenza ukusetshenziswa kwama-skill kubikezeleke kakhulu. Qala ngesibonelo esisebenza ngaphandle kwe-inthanethi, hlanganisa i-skill encane oyethembayo, hlola umhlahlandlela okhiqiziwe, bese wethula ama-trace kancane kancane ngenkathi uqapha imiphumela yokuqinisekisa.