AI 튜토리얼

HEXIS로 신뢰할 수 있는 에이전트 스킬을 상태 머신으로 컴파일하기

HEXIS를 설치하고, 에이전트 스킬을 확장 유한 상태 머신으로 컴파일하며, 실행 추적을 통해 업데이트하고, CLI 또는 Python API로 실행하는 방법을 알아보세요. 또한 머신 개념, 검증, 도구 백엔드, 생성된 가이드, 대체 동작 및 실용적인 보안 고려 사항을 설명합니다.

2026년 9월 17일약 18분 소요

HEXIS란 무엇인가요?

HEXIS는 SKILL.md 문서로 표현된 에이전트 스킬을 확장 유한 상태 머신으로 컴파일하는 Python 패키지이자 명령줄 도구입니다. 언어 모델에 전체 스킬을 해석하고 다음 단계를 모두 선택하도록 요청하는 대신, HEXIS는 프로그래밍 방식의 상태, 변수, 가드, 전이를 사용해 작업 순서를 강제합니다.

언어 모델은 여전히 관련 상태 내에서 추론과 생성을 수행합니다. 하지만 다음 작업이 무엇인지, 어떤 변수를 사용할 수 있는지, 루프를 언제 중지해야 하는지, 어떤 종료 결과에 도달하는지는 머신이 결정합니다. 이 설계는 에이전트가 스킬에 작성된 요구 사항을 건너뛰거나, 순서를 바꾸거나, 잘못 적용할 위험을 줄입니다.

HEXIS는 MIT 라이선스로 배포되며 현재 알파 소프트웨어로 표시되어 있습니다. 이 도구는 에이전트 스킬을 확장 유한 상태 머신으로 컴파일하기 논문과 함께 제공됩니다.

핵심 워크플로

일반적인 HEXIS 워크플로는 세 단계로 구성됩니다.

컴파일: 모델이 스킬 문서, 작업 입력, 도구 정의, 스킬 규칙을 읽고 efsm-v1 머신 초안을 작성합니다. HEXIS는 스키마, 가드, 도달 가능성, 종료, 절 조항 적용 범위, 도구 참조를 검사합니다. 유효하지 않은 초안은 수정을 위해 모델에 반환됩니다.
업데이트: 새로운 실행 추적을 이벤트로 정규화합니다. 각 추적 단계에 대해 모델, 결정 파일 또는 결정론적 정렬기가 기존 상태와 일치시킬지, 상태를 새로 만들지, 노이즈를 무시할지, 추적을 제외할지 결정합니다.
실행: 런타임이 현재 상태에 연결된 작업을 수행하고, 선언된 출력을 기록한 다음, 가드가 true로 평가되는 첫 번째 전이를 실행합니다.

업데이트된 머신은 필수 검사를 통과하고 새로운 추적뿐 아니라 이전에 승인된 모든 추적도 재생할 수 있을 때만 승인됩니다. 검증에 실패하면 기존 머신은 변경되지 않습니다.

주요 기능

OpenAI 호환 컴파일: 명령줄에서 모델, 엔드포인트, API 키 환경 변수의 이름을 선택할 수 있습니다.
추적 기반 업데이트: 이전에 승인된 추적을 무효화하지 않고 성공적인 실행 동작을 한 번에 하나의 결정씩 통합합니다.
가독성 높은 JSON 머신: 머신은 타입이 지정된 변수와 명시적 전이를 사용하는 일반 JSON efsm-v1 형식을 사용합니다.
다양한 작업 유형: 상태는 tool, model, judge, user, end 작업을 수행할 수 있습니다.
제한된 제어 흐름: 순서가 지정된 가드와 루프 카운터가 분기 및 재시도 제한을 지원합니다.
문서 생성: 모든 일반 빌드에는 GUIDE.md와 PROMPT.md가 포함됩니다.
대체 동작: 대체 상태는 가장 최근의 도구 단계부터 재시도하며, 원래 스킬을 해석해 실행하는 방식으로 작업을 넘길 수 있습니다.
도구 백엔드: 머신은 OpenCode 도구, 로컬 Bash 실행기 또는 모델이 구현하는 레지스트리 정의 도구를 사용할 수 있습니다.
격리된 테스트: 저장소에는 API 키, 모델 엔드포인트, 네트워크 연결이 필요하지 않은 테스트가 350개 이상 포함되어 있습니다.

설치 및 사전 요구 사항

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 호환 채팅 엔드포인트가 필요합니다. 기본 실행 백엔드는 PATH에 OpenCode도 있어야 합니다. 머신에 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는 명령줄 옵션 또는 환경 변수에서 모델 식별자, 기본 URL, API 키를 읽습니다. 기본적인 셸 구성은 다음과 같습니다.

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

MODEL, BASE_URL, API_KEY를 .env 파일에 넣을 수도 있습니다. HEXIS는 작업 디렉터리에서 상위 방향으로 검색하며, 환경에 이미 존재하는 변수가 우선합니다.

재사용 가능한 엔드포인트 인수를 셸 변수에 저장하려면 다음과 같이 합니다.

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 머신은 efsm-v1 형식을 사용하는 JSON 문서입니다. 주요 요소는 변수, 상태, 액션, 전이, 터미널 및 폴백 상태입니다.

변수

변수는 init_from을 사용해 작업 입력 필드에서 초기화하거나 init을 사용해 상수 값으로 초기화할 수 있습니다. 액션은 선언된 변수에만 결과를 기록합니다.

액션

Model: 상태별 프롬프트와 선택한 입력 변수를 사용해 선언된 변수를 생성합니다.
Tool: 이름이 지정된 도구를 호출합니다. ${command}와 같은 참조는 실행 시 치환됩니다.
Judge: 고정된 집합에서 레이블을 선택하거나 abstain 레이블을 반환합니다.
User: 사용자 입력을 요청합니다.
End: 터미널 결과와 함께 실행을 중지합니다.

전이와 가드

전이는 상태의 액션이 완료된 후 순서대로 평가됩니다. 런타임은 가드가 참인 첫 번째 전이를 선택합니다. 빈 가드는 무조건 전이이며 마지막에 배치해야 합니다. 전이는 inc를 통해 카운터를 증가시킬 수도 있어 제한된 재시도 루프를 구현할 수 있습니다.

가드는 hexis.machine.cond로 구현된 제한된 표현식 언어를 사용합니다. 이 언어는 상호 배제 및 루프 한계와 같은 속성의 정적 분석을 지원하며 Python의 eval을 사용하지 않습니다.

트레이스에서 머신 업데이트하기

실행 트레이스는 JSON Lines 파일입니다. 작업 메타데이터와 판정으로 시작한 뒤 줄마다 하나의 이벤트가 이어집니다. 트레이스에는 도구 호출, 모델 출력 및 종료 이벤트가 포함될 수 있습니다.

먼저 모델 호출이나 변경 사항 기록 없이 대기 중인 트레이스를 미리 봅니다.

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

그런 다음 업데이트를 수행합니다.

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

각 트레이스 단계에서 결정기는 네 가지 결과 중 하나를 선택합니다.

match는 기존 상태를 재사용하고 필요한 경우 전이를 추가합니다.
new는 명시된 목적을 기반으로 상태를 생성합니다.
ignore는 하네스 노이즈를 고려 대상에서 제거합니다.
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 명령을 실행합니다. 런타임에서 머신은 백엔드가 제공하거나 도구 레지스트리에 정의된 도구만 사용할 수 있으며, 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)

관련 API로는 머신을 로드하는 hexis.machine.schema.load_machine, 엔드포인트를 구성하는 hexis.llm.llm_client.client_from_env, 가이드, 프롬프트, Mermaid 다이어그램을 렌더링하는 hexis.guide 함수가 있습니다.

제공된 예제 머신 사용

저장소에는 examples/machines/ 아래에 컴파일된 머신 네 개가 포함되어 있습니다:

dabench: 계산을 사용하여 데이터 파일에 관한 데이터 분석 질문에 답합니다.
livemath: 정리 기반 객관식 수학 문제에 답합니다.
sealqa: 로컬 코퍼스에서 질문에 답하고 근거를 포함합니다.
spreadsheet: 구조를 변경하지 않고 통합 문서를 편집합니다.

이러한 머신은 일반적으로 모델 상태에서 셸 명령을 작성하고, 도구 상태에서 이를 실행하며, 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을 추가합니다.

명시적 도구 정의 제공

머신에서 사용자 지정 도구를 사용하는 경우 --tools registry.json을 전달합니다. 컴파일 중 도구 이름은 불투명한 식별자로 처리됩니다. 런타임에서 레지스트리에 정의된 도구는 모델이 셸 명령으로 구현할 수 있지만, 네이티브 도구는 선택한 백엔드가 제공해야 합니다.

모델 요청 조정

컴파일 및 업데이트는 --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는 셸 명령을 포함하여 언어 모델이 생성한 도구 인수를 실행할 수 있습니다. 신뢰할 수 없는 워크로드는 격리된 환경에서 실행하고, 신뢰하는 머신, 스킬, 레지스트리 및 작업 파일만 사용하십시오.

업데이트 과정에서는 추적 단계, 축약된 도구 결과 및 스킬 조항이 구성된 모델 엔드포인트로 전송됩니다. 빌드 디렉터리에는 추적 사본과 모델 질문이 보존됩니다. 또한 PROMPT.md에는 스킬에서 파생된 전체 머신과 프롬프트가 포함됩니다. 이러한 아티팩트를 공유하기 전에 검토하십시오.

런타임은 모든 호출에 전체 머신을 노출하는 대신, 각 모델 호출을 현재 실행 중인 상태의 프롬프트로 제한합니다.

결론

HEXIS는 자연어 에이전트 지침을 명시적이고 검증된 워크플로로 변환합니다. 상태 내부의 모델 추론을 프로그래밍 방식의 전환, 추적 재생, 제한된 재시도, 도구 제한, 생성된 가이드 및 폴백 처리와 결합하여 스킬 실행을 더욱 예측 가능하게 만드는 구조화된 방법을 제공합니다. 오프라인 예제로 시작하고, 신뢰할 수 있는 작은 스킬을 컴파일한 뒤, 생성된 가이드를 검토하고, 검증 결과를 모니터링하면서 추적을 점진적으로 도입하십시오.