Biên dịch Kỹ năng Tác nhân Đáng tin cậy thành Máy trạng thái với HEXIS

HEXIS là gì?

HEXIS là một gói Python và công cụ dòng lệnh biên dịch một kỹ năng tác tử, được biểu diễn bằng tài liệu SKILL.md, thành một máy trạng thái hữu hạn mở rộng. Thay vì yêu cầu mô hình ngôn ngữ diễn giải toàn bộ kỹ năng và chọn từng bước tiếp theo, HEXIS sử dụng các trạng thái, biến, điều kiện bảo vệ và chuyển tiếp theo chương trình để áp đặt thứ tự thao tác.

Mô hình ngôn ngữ vẫn thực hiện việc suy luận và sinh nội dung bên trong các trạng thái liên quan. Tuy nhiên, máy sẽ xác định thao tác nào chạy tiếp theo, biến nào khả dụng, khi nào vòng lặp phải dừng và kết quả cuối nào được đạt tới. Thiết kế này làm giảm nguy cơ tác tử bỏ qua, sắp xếp lại hoặc áp dụng sai các yêu cầu được viết trong kỹ năng.

HEXIS được phát hành theo giấy phép MIT và hiện được đánh dấu là phần mềm alpha. Dự án đi kèm bài báo Biên dịch kỹ năng tác tử thành máy trạng thái hữu hạn mở rộng.

Quy trình cốt lõi

Một quy trình HEXIS điển hình có ba giai đoạn:

1. Biên dịch: Một mô hình đọc tài liệu kỹ năng, đầu vào tác vụ, định nghĩa công cụ và các quy tắc của kỹ năng, sau đó phác thảo một máy efsm-v1. HEXIS kiểm tra lược đồ, điều kiện bảo vệ, khả năng truy cập, việc kết thúc, mức độ bao phủ mệnh đề và các tham chiếu công cụ. Các bản phác thảo không hợp lệ được gửi lại cho mô hình để chỉnh sửa.
2. Cập nhật: Các dấu vết thực thi mới được chuẩn hóa thành các sự kiện. Với mỗi bước trong dấu vết, một mô hình, tệp quyết định hoặc bộ căn chỉnh xác định sẽ quyết định việc khớp với trạng thái hiện có, tạo trạng thái mới, bỏ qua nhiễu hay loại trừ dấu vết.
3. Thực thi: Runtime thực hiện hành động gắn với trạng thái hiện tại, ghi lại các đầu ra đã khai báo và thực hiện chuyển tiếp đầu tiên có điều kiện bảo vệ được đánh giá là đúng.

Một máy đã cập nhật chỉ được chấp nhận khi vượt qua các kiểm tra bắt buộc và có thể phát lại dấu vết mới cũng như mọi dấu vết đã được chấp nhận trước đó. Nếu xác thực thất bại, máy hiện tại vẫn không thay đổi.

Tính năng chính

• Biên dịch tương thích với OpenAI: Chọn mô hình, endpoint và biến môi trường chứa khóa API từ dòng lệnh.
• Cập nhật dựa trên dấu vết: Tích hợp hành vi thực thi thành công từng quyết định một mà không làm mất hiệu lực các dấu vết đã được chấp nhận trước đó.
• Máy JSON dễ đọc: Máy sử dụng định dạng JSON thuần efsm-v1 với các biến có kiểu và các chuyển tiếp rõ ràng.
• Nhiều loại hành động: Các trạng thái có thể thực hiện hành động tool, model, judge, user hoặc end.
• Luồng điều khiển có giới hạn: Các điều kiện bảo vệ theo thứ tự và bộ đếm vòng lặp hỗ trợ rẽ nhánh cùng giới hạn thử lại.
• Tài liệu được sinh tự động: Mỗi lần build thông thường đều bao gồm GUIDE.md và PROMPT.md.
• Hành vi dự phòng: Trạng thái dự phòng thử lại từ bước công cụ gần nhất và có thể chuyển tác vụ sang chế độ thực thi được diễn giải của kỹ năng gốc.
• Backend công cụ: Máy có thể sử dụng công cụ OpenCode, bộ thực thi Bash cục bộ hoặc các công cụ được định nghĩa trong registry và được hiện thực hóa bởi mô hình.
• Kiểm thử khép kín: Kho mã chứa hơn 350 bài kiểm thử không yêu cầu khóa API, endpoint mô hình hoặc kết nối mạng.

Cài đặt và điều kiện tiên quyết

Cài đặt từ PyPI

HEXIS yêu cầu Python 3.11 hoặc 3.12. Cài đặt gói bằng pip:

pip install hexis-agent

Trong Python, gói này được import dưới tên hexis, còn tệp thực thi dòng lệnh có tên hexis-agent.

Cài đặt từ bản sao kho mã

pip install .

Để cài đặt các dependency phát triển như pytest, Ruff, build và Twine, hãy sử dụng cài đặt editable:

pip install -e ".[dev]"

Yêu cầu runtime

Việc biên dịch và chạy các máy có mô hình hỗ trợ yêu cầu một chat endpoint tương thích với OpenAI. Backend thực thi mặc định cũng yêu cầu OpenCode có trong PATH. Nếu máy chỉ cần Bash, hãy chọn --executor local để chạy lệnh trong một subprocess cục bộ mà không cần OpenCode.

Thử bắt đầu nhanh ngoại tuyến

Gói này bao gồm một ví dụ khép kín nhỏ có tên table_clean. Ví dụ sử dụng mô hình được lập trình sẵn, các công cụ được lập trình sẵn và hệ thống tệp trong bộ nhớ, nên có thể chạy mà không cần truy cập mạng.

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

Ví dụ sẽ kết thúc với một kết quả cuối, in ra đường đi qua các trạng thái và cho biết dấu vết được tạo có vượt qua bộ xác minh của ví dụ hay không. Đây là cách hữu ích để xác nhận quá trình cài đặt đã thành công trước khi cấu hình một endpoint bên ngoài.

Cấu hình endpoint mô hình

HEXIS đọc mã định danh mô hình, URL cơ sở và khóa API từ các tùy chọn dòng lệnh hoặc biến môi trường. Cấu hình shell cơ bản như sau:

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

Bạn cũng có thể đặt MODEL, BASE_URL và API_KEY trong tệp .env. HEXIS tìm kiếm từ thư mục làm việc trở lên, và các biến đã có trong môi trường sẽ được ưu tiên.

Để lưu các đối số endpoint có thể tái sử dụng trong một biến shell:

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

Tùy chọn --api-key-env NAME chọn một biến môi trường khác để lưu khóa. Khóa API không được truyền trên dòng lệnh hoặc lưu trong bản kê khai bản dựng.

Biên dịch một kỹ năng thành máy

Trỏ trình biên dịch đến đường dẫn kỹ năng và chọn thư mục đầu ra:

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

Thư mục kỹ năng phải chứa SKILL.md. Thư mục này cũng có thể chứa compile.json, trong đó khai báo các trạng thái kết thúc, nhãn sự kiện dẫn xuất, yêu cầu và điều kiện kết thúc. Mỗi quy tắc trong tệp đó đều trích dẫn câu mà nó được suy ra.

Nếu không có compile.json, trình biên dịch sẽ yêu cầu mô hình trích xuất các quy tắc từ kỹ năng và đối chiếu phần văn bản được trích dẫn với tài liệu. Cấu hình hiệu lực sau đó được lưu dưới dạng rules.json.

Thư mục bản dựng chứa gì

• machine.json lưu máy hiện tại.
• machine_init.json giữ lại máy được biên dịch ban đầu.
• build.json ghi lại thông tin nguồn, cài đặt lệnh, chi tiết mô hình, kết quả và lượng token đã sử dụng, nhưng không bao giờ lưu khóa API.
• skill/SKILL.md, tools.json và rules.json lưu lại các đầu vào biên dịch.
• traces/ chứa các bản sao đã băm của những dấu vết được bản dựng sử dụng.
• progress.json ghi lại kết quả dấu vết và các dấu vết được chấp nhận dùng để bảo vệ máy.
• decisions.jsonl lưu bộ nhớ đệm cho các câu hỏi và câu trả lời cập nhật.
• report.md, context.json và các tệp nhật ký cung cấp thông tin chẩn đoán.
• GUIDE.md giải thích các đầu vào, công cụ, trạng thái, chuyển tiếp, vòng lặp và hành vi dự phòng.
• PROMPT.md cung cấp lời nhắc hệ thống cho tác nhân sử dụng công cụ để thực thi máy theo từng trạng thái.

Tìm hiểu mô hình máy

Máy HEXIS là một tài liệu JSON sử dụng định dạng efsm-v1. Các thành phần chính gồm biến, trạng thái, hành động, chuyển tiếp, trạng thái kết thúc và trạng thái dự phòng.

Biến

Các biến có thể được khởi tạo từ các trường đầu vào của tác vụ bằng init_from hoặc từ các giá trị hằng bằng init. Hành động chỉ ghi kết quả vào các biến đã khai báo.

Hành động

• Mô hình: Tạo các biến đã khai báo từ lời nhắc dành riêng cho trạng thái và các biến đầu vào được chọn.
• Công cụ: Gọi một công cụ có tên. Các tham chiếu như ${command} được thay thế khi chạy.
• Bộ phán định: Chọn một nhãn từ tập cố định hoặc trả về nhãn abstain.
• Người dùng: Yêu cầu dữ liệu đầu vào từ người dùng.
• Kết thúc: Dừng thực thi với một kết quả kết thúc.

Chuyển tiếp và điều kiện bảo vệ

Các chuyển tiếp được đánh giá theo thứ tự sau khi hành động của một trạng thái hoàn tất. Runtime chọn chuyển tiếp đầu tiên có điều kiện bảo vệ đúng. Điều kiện bảo vệ trống là không điều kiện và nên xuất hiện cuối cùng. Một chuyển tiếp cũng có thể tăng bộ đếm thông qua inc, cho phép tạo các vòng lặp thử lại có giới hạn.

Các điều kiện bảo vệ sử dụng ngôn ngữ biểu thức bị giới hạn do hexis.machine.cond triển khai. Ngôn ngữ này hỗ trợ phân tích tĩnh các thuộc tính như loại trừ lẫn nhau và giới hạn vòng lặp, đồng thời không sử dụng eval của Python.

Cập nhật máy từ các dấu vết

Các dấu vết thực thi là các tệp JSON Lines. Chúng bắt đầu bằng siêu dữ liệu tác vụ và một phán quyết, tiếp theo là một sự kiện trên mỗi dòng. Một dấu vết có thể chứa các lệnh gọi công cụ, đầu ra mô hình và một sự kiện kết thúc.

Trước tiên, xem trước các dấu vết đang chờ xử lý mà không gọi mô hình hoặc ghi thay đổi:

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

Sau đó thực hiện cập nhật:

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

Đối với mỗi bước của dấu vết, bộ quyết định chọn một trong bốn kết quả:

• match sử dụng lại một trạng thái hiện có và thêm một chuyển tiếp nếu cần.
• new tạo một trạng thái dựa trên mục đích đã nêu.
• ignore loại bỏ nhiễu từ bộ kiểm thử khỏi quá trình xem xét.
• exclude loại toàn bộ dấu vết.

Câu trả lời của mô hình cũng xác định một trạng thái ứng viên, mô tả mục đích của bước và có thể liên kết bước đó với một điều khoản kỹ năng. HEXIS xác thực máy ứng viên thu được và phát lại tất cả các dấu vết được bảo vệ trước khi chấp nhận.

Tiếp tục và kiểm soát chi phí cập nhật

Các câu trả lời của mô hình được lưu trong bộ nhớ đệm tại decisions.jsonl. Việc lặp lại cùng một lệnh sẽ sử dụng lại các câu trả lời đó, còn một lần chạy bị gián đoạn với trạng thái thoát 3 có thể tiếp tục từ tiến trình đã lưu. Chỉ sử dụng --no-cache khi bạn thực sự muốn mô hình trả lời lại.

Một lần cập nhật thường tốn khoảng một lượt gọi mô hình cho mỗi bước dấu vết. Sử dụng --max-traces N để giới hạn một lần chạy. Đối với các lựa chọn không dùng mô hình, hãy cung cấp quyết định của con người hoặc hệ thống bên ngoài qua --decisions FILE, hoặc chọn căn chỉnh xác định bằng --decider align.

Trước khi xử lý các dấu vết mới, HEXIS kiểm tra máy hiện tại và phát lại mọi dấu vết đã chấp nhận. Nếu một chỉnh sửa thủ công hoặc định nghĩa công cụ đã thay đổi làm hỏng bản dựng, lệnh sẽ thoát với trạng thái 2 mà không sửa đổi bản dựng.

Chạy máy đã biên dịch

Kiểm tra build/GUIDE.md trước khi thực thi. Tệp này ghi lại các đầu vào tác vụ bắt buộc, công cụ khả dụng, hành động trạng thái, thứ tự chuyển tiếp, giới hạn thử lại và hành vi dự phòng.

Chạy máy với các đầu vào tác vụ dạng khóa-giá trị:

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

Truyền thêm các tùy chọn --input KEY=VALUE cho mọi đầu vào mà máy yêu cầu. Để lưu lần thực thi dưới dạng nhật ký JSON Lines có thể tái sử dụng, hãy thêm:

--json run-trace.jsonl

Bộ thực thi mặc định sử dụng các công cụ OpenCode. Bộ thực thi cục bộ chạy các lệnh Bash trong một tiến trình con. Khi chạy, máy chỉ có thể sử dụng các công cụ do backend cung cấp hoặc được định nghĩa trong một registry công cụ; HEXIS không âm thầm thay thế các công cụ bị thiếu.

Sử dụng máy từ Python

Điểm vào runtime cốt lõi là hexis.execution.runtime.run_task. Cung cấp một máy đã tải, một tác vụ có đối tượng input, một bộ chuyển đổi mô hình, một registry công cụ và tài liệu kỹ năng khi quá trình thực thi dự phòng có thể cần đến tài liệu này.

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)

Các API liên quan gồm hexis.machine.schema.load_machine để tải máy, hexis.llm.llm_client.client_from_env để cấu hình endpoint và các hàm trong hexis.guide để kết xuất hướng dẫn, prompt và sơ đồ Mermaid.

Làm việc với các máy mẫu được cung cấp

Kho mã nguồn bao gồm bốn máy đã biên dịch trong examples/machines/:

• dabench: Trả lời câu hỏi phân tích dữ liệu về một tệp dữ liệu bằng phép tính.
• livemath: Trả lời câu hỏi toán trắc nghiệm dựa trên định lý.
• sealqa: Trả lời câu hỏi từ kho dữ liệu cục bộ và kèm theo bằng chứng.
• spreadsheet: Chỉnh sửa sổ tính mà không thay đổi cấu trúc.

Các máy này thường sử dụng một trạng thái mô hình để viết lệnh shell, một trạng thái công cụ để thực thi lệnh, cơ chế thử lại có điều kiện dựa trên returncode, một bước công cụ để đọc lại câu trả lời và một trạng thái đánh giá để chọn terminal đã xác minh hoặc chưa xác minh.

Ví dụ, chạy máy LiveMath bằng:

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

Có thể tải và kiểm tra cấu trúc các máy mẫu mà không cần mô hình, nhưng để chạy chúng cần một endpoint mô hình đã được cấu hình.

Mẹo nâng cao

Tạo lại tài liệu

Quá trình biên dịch và cập nhật sẽ tự động tạo tài liệu trừ khi sử dụng --no-guide. Tạo lại tài liệu thủ công bằng:

hexis-agent guide --build build/

Bạn cũng có thể trỏ trực tiếp lệnh đến machine.json. Thêm --embed-skill khi muốn prompt agent được tạo ra bao gồm kỹ năng gốc, cho phép thực thi diễn giải sau khi chuyển sang cơ chế dự phòng.

Cung cấp định nghĩa công cụ tường minh

Truyền --tools registry.json khi máy sử dụng các công cụ tùy chỉnh. Tên công cụ được xem là các mã định danh không cần diễn giải trong quá trình biên dịch. Khi chạy, các công cụ được định nghĩa trong registry có thể được mô hình hiện thực hóa thành lệnh shell, còn các công cụ gốc phải được backend đã chọn cung cấp.

Tinh chỉnh yêu cầu mô hình

Quá trình biên dịch và cập nhật hỗ trợ các tùy chọn như --temperature, --max-tokens, --llm-timeout, --llm-retries, --stream và --extra-body JSON. Với các endpoint tương thích Qwen, có thể kiểm soát suy luận runtime bằng --no-think, --think-budget và --judge-think-budget.

Sử dụng biến môi trường riêng cho từng nhà cung cấp

Tùy chọn --provider NAME đọc các biến NAME_MODEL, NAME_BASE_URL và NAME_API_KEY. Các giá trị mặc định tích hợp sẵn có cho tên nhà cung cấp MiniMax và DeepSeek.

Nắm rõ các trạng thái thoát

• 0 cho biết thành công.
• 2 cho biết có vấn đề về cách sử dụng, cấu hình hoặc quá trình biên dịch.
• 3 cho biết endpoint mô hình gặp lỗi hoặc bị gián đoạn; tiến trình được lưu để tiếp tục.

Chạy các bước kiểm tra dành cho phát triển

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

Bộ kiểm thử có tính cô lập. Các kiểm thử dành riêng cho OpenCode sẽ được bỏ qua khi không có tệp thực thi opencode.

Bảo mật và quyền riêng tư

HEXIS có thể thực thi các tham số công cụ do mô hình ngôn ngữ tạo ra, bao gồm cả lệnh shell. Hãy chạy các workload không đáng tin cậy trong môi trường cô lập và chỉ sử dụng những máy, kỹ năng, registry và tệp tác vụ mà bạn tin cậy.

Quá trình cập nhật gửi các bước trace, kết quả công cụ đã rút gọn và các mệnh đề kỹ năng đến endpoint mô hình được cấu hình. Các thư mục build lưu lại bản sao trace và các câu hỏi gửi mô hình. Ngoài ra, PROMPT.md chứa toàn bộ máy và các prompt được tạo từ kỹ năng. Hãy xem xét các tạo tác này trước khi chia sẻ.

Runtime giới hạn mỗi lần gọi mô hình vào prompt của trạng thái đang được thực thi, thay vì cung cấp toàn bộ máy cho mọi lần gọi.

Kết luận

HEXIS biến các chỉ dẫn agent bằng ngôn ngữ tự nhiên thành các quy trình rõ ràng và được xác thực. Bằng cách kết hợp suy luận của mô hình bên trong các trạng thái với chuyển tiếp theo chương trình, phát lại trace, cơ chế thử lại có giới hạn, hạn chế công cụ, hướng dẫn được tạo tự động và xử lý dự phòng, HEXIS cung cấp một cách có cấu trúc để làm cho việc thực thi kỹ năng dễ dự đoán hơn. Hãy bắt đầu với ví dụ ngoại tuyến, biên dịch một kỹ năng nhỏ đáng tin cậy, kiểm tra hướng dẫn được tạo ra, sau đó từng bước đưa trace vào sử dụng trong khi theo dõi kết quả xác thực.