Omnigent: một harness cho nhiều agent CLI

Omnigent là gì

Omnigent là một meta-harness mã nguồn mở: một lớp orchestration điều khiển các công cụ dòng lệnh của agent (CLI) đã được cài trên hệ thống. Nó không thay thế Claude Code, Codex, Cursor, OpenCode, Hermes hoặc Pi. Nó khởi chạy các công cụ này, giao nhiệm vụ cho từng công cụ và giám sát kết quả trong một session duy nhất với cùng một bộ policy. Databricks đã công bố repository này vào tháng 6 năm 2026 theo giấy phép Apache 2.0, và trang đầu vẫn hiển thị Status: alpha.

Phạm vi tuyên bố thực tế khá hẹp và cần được nói rõ. Bạn mô tả một agent một lần bằng YAML, rồi chỉ định harness chạy agent đó. Chỉ cần thay đổi dòng này là cùng agent có thể chạy trên CLI của vendor khác. Các phần còn lại trong thiết lập không thay đổi, vì Omnigent quản lý vòng lặp bên trên các agent thay vì vòng lặp bên trong chúng.

Meta-harness là gì và khác framework như thế nào?

Harness là chương trình bọc một model trong một vòng lặp. Nó đọc prompt, gọi tool, chỉnh sửa file và trả kết quả. Claude Code là một harness. Codex là một harness. Bạn cài đặt nó, đăng nhập và nó tự hoạt động.

Framework là một thư viện mà bạn viết code dựa trên đó. Bạn import thư viện, định nghĩa các bước bằng Python, rồi chương trình của bạn trở thành agent. Khi đổi vendor, bạn phải sửa code, vì client của vendor được tích hợp qua chương trình của bạn.

Meta-harness nằm cao hơn cả hai một lớp. Đây là một supervisor chạy các harness dưới dạng tiến trình con. Omnigent khởi động CLI của vendor, giao việc cho CLI và đọc kết quả trả về. Bạn tiếp tục dùng CLI đã cài sẵn và subscription hoặc API (application programming interface) key đang dùng để thanh toán cho CLI đó. Đó là toàn bộ điểm khác biệt. Điểm này cũng xác định công cụ dành cho ai: những người đã có nhiều agent CLI hoạt động và không muốn điều khiển từng CLI một trong từng terminal.

Giải quyết vấn đề gì khi dùng một lớp orchestration?

• Đổi vendor chỉ cần sửa một dòng. Định nghĩa agent lưu harness và model dưới dạng dữ liệu, nên chuyển một vai trò từ vendor này sang vendor khác chỉ cần sửa file YAML, không phải viết lại.
• Có thể review giữa các vendor. Một model viết diff được model của công ty khác đọc lại. Hai model cùng một family thường có cùng điểm mù, nên ý kiến thứ hai từ cùng vendor có giá trị thấp hơn.
• Policy có một nơi quản lý duy nhất. Giới hạn chi phí và các prompt yêu cầu phê duyệt được khai báo trong file agent, rồi áp dụng cho mọi sub-agent bên dưới.
• Session không phụ thuộc vào một tool duy nhất. Một transcript bao quát công việc thực hiện bằng nhiều CLI, nên bạn có thể xem lại những gì đã xảy ra mà không phải ghép 4 vùng scrollback.

Chi phí nằm ở chính lớp này. Mọi bug trong Omnigent giờ trở thành một bug nằm giữa bạn và agent vốn có thể tự hoạt động. Ở giai đoạn alpha, đây là chi phí thực tế, không phải rủi ro trên lý thuyết.

Multi-agent harness nằm ở đâu so với các công cụ single agent

Nếu bạn chưa từng chạy một agent trên server, hãy bắt đầu từ đó. Hướng dẫn chạy coding agent trên VPS của chúng tôi bao quát toàn bộ trường hợp single agent. Đây cũng là cấu hình mà Omnigent giả định bạn đã có. Hệ sinh thái các AI agent self-hosted giúp bạn chọn agent. Nếu các thuật ngữ trong phần này còn mới, tìm hiểu cách agent thực sự hoạt động sẽ là điểm bắt đầu phù hợp hơn.

Omnigent cũng khác với một connector layer. Nội dung như cho agent truy cập các nguồn dữ liệu của bạn nói về những gì agent có thể truy cập. Omnigent nói về agent nào sẽ chạy, chạy theo thứ tự nào và chịu những giới hạn nào. Bạn có thể cần cả hai cùng lúc. Hai phần này không trùng lặp.

Những thứ cần có trước khi cài đặt

• Python 3.12 trở lên. Package đã phát hành khai báo requires-python >= 3.12.
• tmux, vì các terminal harness chạy bên trong đó.
• Ít nhất một vendor CLI đã được cài đặt và đăng nhập.
• Chỉ cần Node.js 22 nếu bạn build từ một git checkout. Wheel trên PyPI đã chứa sẵn web asset đã build, nên cách cài đặt thông thường hoàn toàn không cần Node.

Cài bản phát hành cố định, không dùng nhánh main

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --version 0.7.0

Phần sh -s -- không phải để trang trí. Nếu thiếu phần này, sh sẽ đọc --version như một tùy chọn riêng và trình cài đặt không nhận được flag đó, nên bạn sẽ nhận bất cứ bản mới nhất nào tại thời điểm chạy. Với một repository phát hành các thay đổi breaking vài tuần một lần, đây là khác biệt giữa một máy chủ có thể tái lập và một sự cố bất ngờ.

Trình cài đặt dùng uv, trình quản lý package Python của Astral, và đề nghị cài uv trước nếu chưa có. Nếu uv đã được cài, hãy bỏ qua script:

uv tool install --force --python 3.12 "omnigent==0.7.0"

Các extra cũng dùng cùng mẫu, và flag cũng lặp lại: --extra e2b --extra kubernetes trên script hoặc "omnigent[e2b,kubernetes]" với uv. Lưu ý rằng git tag là v0.7.0, còn phiên bản package trên PyPI là 0.7.0.

uv đặt binary vào thư mục mà uv tool dir --bin báo cáo, thường là ~/.local/bin, và trình cài đặt đề nghị thêm thư mục đó vào shell profile của bạn. Nếu command không được tìm thấy ngay sau khi cài mới, đó là lý do. Kiểm tra những gì đã được cài:

omni upgrade --check

Lệnh này so sánh phiên bản đã cài với phiên bản mới nhất đã phát hành và cho biết có bản nâng cấp hay không, nhưng không thực hiện nâng cấp. omni và omnigent là cùng một chương trình với hai tên khác nhau.

Trỏ đến một nhà cung cấp model

omni setup

Trình hướng dẫn tìm credential đã có trong môi trường của bạn và hỏi những credential còn thiếu. Trình hướng dẫn hỗ trợ API key, subscription của vendor, các gateway như OpenRouter hoặc Ollama và workspace Databricks. Nếu bạn đã chạy một model server cục bộ bằng Ollama trên cùng máy, hãy trỏ một gateway đến server đó để traffic không bao giờ rời khỏi máy.

Một lần chạy multi-agent tối giản

Các agent mẫu nằm trong repository, vì vậy hãy clone đúng tag bạn đã cài đặt thay vì main.

git clone --depth 1 --branch v0.7.0 https://github.com/omnigent-ai/omnigent.git
cd omnigent
omnigent run examples/polly/

Polly là bộ điều phối coding multi-agent đi kèm repository. Cấu hình của nó khai báo các sub-agent có tên claude_code, codex, opencode, cursor, hermes và pi, cùng một quy tắc khiến toàn bộ bài thực hành này đáng chạy: việc review luôn do vendor khác với người implement thực hiện. Polly không tự viết code. Nó lập kế hoạch, chia mục tiêu thành các work item, giao từng item cho agent phù hợp và chuyển từng diff đến reviewer thuộc vendor khác.

Trước khi giao việc, Polly chạy kiểm tra preflight để xác định những sub-agent CLI nào thực sự tồn tại trên máy. Nếu chỉ cài CLI của một vendor thì không có ai để nhận diff, vì vậy hãy cài ít nhất hai CLI trước khi đánh giá output. Debby là ví dụ khác đi kèm repository. Đây là một debate agent có hai head: một head dùng Claude và một head dùng GPT:

omni debby

Đây là cách nhanh để xác nhận đã cấu hình hai provider, vì Debby cần cả hai provider mới có thể đưa ra phản hồi.

Khai báo sub-agent dưới dạng tool

File agent dùng YAML. executor khai báo harness, model và thông tin xác thực. tools chứa các server MCP (model context protocol), hàm Python và sub-agent. Sub-agent là một tool có type: agent và executor riêng. Đây là cơ chế đứng sau tất cả các thành phần trên.

name: orchestrator
prompt: |
  You coordinate coding and review tasks.

executor:
  harness: claude-sdk
  model: databricks-claude-sonnet-4-6

tools:
  coder:
    type: agent
    prompt: Write and test code.
    executor:
      harness: claude-sdk
      model: databricks-claude-opus-4-7
  reviewer:
    type: agent
    prompt: Review proposed changes.
    executor:
      harness: claude-sdk
      model: databricks-claude-sonnet-4-6

omnigent run path/to/my_agent.yaml

Các model id đó lấy từ ví dụ docs/AGENT_YAML_SPEC.md của chính project và là những tên được Databricks host. Thay harness và model bằng các giá trị omni setup đã cấu hình trên máy của bạn. Các giá trị harness khác trong spec gồm antigravity, copilot, kimi, qwen và acp:<slug> cho mọi thành phần giao tiếp bằng generic protocol. Spec cũng hỗ trợ pass_history: true trên sub-agent để truyền cho nó conversation của parent. Tùy chọn này tiêu tốn token trong mỗi lần delegation, vì vậy hãy tắt nó đối với các sub-agent chỉ cần task hiện tại.

Vì sao tác vụ orchestration chạy lâu nên đặt trên VPS

Một lần chạy multi-agent không phải là lệnh chạy trong hai phút. Bạn cần lập kế hoạch, giao việc, chờ các git worktree chạy song song, rồi review và chỉnh sửa. Đóng nắp laptop sẽ dừng toàn bộ quá trình. VPS (virtual private server) luôn hoạt động và duy trì kết nối mạng, nên session vẫn tiếp tục khi bạn không theo dõi.

omnigent server --background
omnigent server status

Server cung cấp web user interface tại port 6767. omnigent server status cho biết hiện có một phiên đang chạy hay không, còn omnigent stop sẽ dừng phiên đó. Trong các bản release trước v0.7.0, lệnh này là omni server start, nhưng lệnh đó đã bị xóa. Vì vậy, các bài viết và ảnh chụp màn hình cũ có thể không khớp với nội dung hiển thị trong terminal của bạn.

Không publish port 6767 trên địa chỉ public. Có 2 cách triển khai an toàn. Giữ port này đóng trên firewall và forward qua SSH bằng ssh -N -L 6767:localhost:6767 you@your-server, sau đó mở web interface tại http://localhost:6767 trên máy của bạn. Hoặc terminate TLS (transport layer security) ở phía trước và bật authentication:

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

Phần cấu hình firewall là công việc thông thường, đã được trình bày trong kiến thức cơ bản về ufw firewall cho VPS. Nếu máy đã chạy các container phía sau Traefik đứng trước nhiều ứng dụng Docker Compose thì Omnigent chỉ là một service khác theo cùng mô hình.

Khi deploy bằng container, thư mục deploy/ của repository chứa cấu hình Compose: ./bootstrap.sh tạo secrets vào .env, sau đó docker compose up -d khởi động Omnigent và Postgres trên port 6767. DATABASE_URL chọn Postgres hoặc SQLite. Theo mặc định, OMNIGENT_AUTH_ENABLED dùng 1 bên trong các container; đây là giá trị mặc định phù hợp cho mọi dịch vụ có thể truy cập từ bên ngoài.

Về cấu hình máy, tài liệu deploy ước tính working set của server ở mức khoảng 512 MB đến 1 GB, còn cấu hình Fly.io cố định ở 1 GB. Con số đó chỉ dành cho supervisor. Mỗi sub-agent là một process riêng, giữ checkout riêng và model client riêng, nên bạn phải chọn cấu hình máy dựa trên số agent. Sau khi server hoạt động, omnigent login https://your-host rồi omnigent host https://your-host sẽ đăng ký laptop của bạn với server đó, còn omnigent attach <session_id> sẽ tiếp tục một session đang chạy từ thiết bị khác.

Cô lập sandbox cho mọi sub-agent trước khi rời máy

Omnigent cung cấp sandbox ở cấp hệ điều hành có tên Omnibox. Trên Linux, nó dùng namespace của bubblewrap cùng với seccomp, nên kernel thực thi ranh giới cô lập thay vì dựa vào prompt của agent. Agent bị prompt injection không thể dùng lời lẽ để vượt qua quy tắc của kernel. Trước tiên, hãy cài dependency:

sudo apt install bubblewrap

Cấu hình nằm dưới os_env trong file agent:

os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: linux_bwrap
    write_paths: [.]
    write_files: []
    read_paths: []
    allow_network: true
    cwd_allow_hidden: [.venv]
    env_passthrough: []
    egress_rules: []
    credential_proxy: []

Working directory ở chế độ chỉ đọc cho đến khi bạn liệt kê nó trong write_paths, nên agent gặp lỗi không thể ghi ra ngoài workspace. Dotfile vẫn bị ẩn trừ khi được chỉ định trong cwd_allow_hidden. Vì vậy, quyền đọc rộng không âm thầm làm lộ .ssh hoặc .aws. Đặt egress_rules để toàn bộ traffic HTTP và HTTPS đi qua proxy mặc định từ chối mọi kết nối, với từng rule được ghi theo dạng "METHODS host/path-glob". credential_proxy đi xa hơn một bước: agent chỉ giữ một placeholder, còn proxy sẽ thay placeholder bằng secret thật khi request rời khỏi hệ thống. Vì vậy, transcript bị lộ cũng không làm lộ secret có thể sử dụng. Trong thiết lập nhiều harness, mỗi sub-agent có block sandbox riêng trong file cấu hình riêng dưới agents/. Nhờ đó, bạn có thể chặn network của reviewer trong khi vẫn cho implementer sử dụng network.

Giới hạn này được nêu trong tài liệu và rất quan trọng. Sandbox của hệ điều hành áp dụng cho các lần gọi tool sys_os_* và terminal. Nó không áp dụng cho MCP server và cũng không áp dụng cho chính tiến trình supervisor của Omnigent. MCP server do bạn khởi động sẽ chạy bên ngoài sandbox với các quyền của bạn. Đây là lý do pattern an toàn hơn vẫn là dùng một máy tạm thời riêng cho mỗi agent. Nội dung này được trình bày trong chạy coding agent trong VM dùng một lần. Phần còn lại là credential. Việc giữ secret ngoài tầm với của agent sẽ khó hơn chứ không dễ hơn khi sáu sub-agent dùng chung một host.

Giới hạn chi phí là các policy được khai báo trong cùng file:

policies:
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00
      ask_thresholds_usd: [1.00, 3.00]

Một run lập kế hoạch bằng một vendor, triển khai bằng vendor thứ hai và review bằng vendor thứ ba sẽ phát sinh chi phí ở ba nơi cùng lúc. Vì vậy, hãy đặt giới hạn trước lần chạy unattended đầu tiên, thay vì đợi đến sau invoice đầu tiên. Các tùy chọn tích hợp cũng gồm max_tool_calls_per_session và ask_on_os_tools, tùy chọn này yêu cầu phê duyệt trước các thao tác với file và shell. Các ghi chú của chúng tôi về kiểm soát chi phí AI agent trên VPS áp dụng trực tiếp ở đây, và còn quan trọng hơn, vì các sub-agent chạy song song sẽ nhân mức tiêu thụ chi phí.

Kho lưu trữ này phát triển nhanh đến mức nào?

[
  {
    "version": "v0.2.0",
    "released": "2026-06-19",
    "interval": 3
  },
  {
    "version": "v0.3.0",
    "released": "2026-06-27",
    "interval": 8
  },
  {
    "version": "v0.4.0",
    "released": "2026-07-03",
    "interval": 6
  },
  {
    "version": "v0.5.0",
    "released": "2026-07-10",
    "interval": 7
  },
  {
    "version": "v0.5.1",
    "released": "2026-07-10",
    "interval": 0
  },
  {
    "version": "v0.6.0",
    "released": "2026-07-21",
    "interval": 11
  },
  {
    "version": "v0.7.0",
    "released": "2026-07-27",
    "interval": 6
  }
]

Đó là ngày phát hành được công bố trên trang releases của chính dự án, được ghi nhận vào ngày 3 August 2026. Có 7 bản phát hành được gắn tag trong khoảng từ 2026-06-19 đến 2026-07-27, và khoảng cách dài nhất giữa hai bản bất kỳ là 11 ngày. v0.5.1 được phát hành cùng ngày với bản phát hành ngay trước đó. Bản phát hành đầu tiên, 0.1.1 vào ngày 16 June 2026, không được đưa vào biểu đồ vì không có tag trước đó để làm mốc đo.

Hai bản phát hành trong số đó đã làm hỏng các command mà các hướng dẫn trước đó đã ghi lại. v0.7.0 đã xóa omni server start để thay bằng omni server --background. v0.6.0 đổi tên extra omnigent[memory] thành omnigent[hindsight], nên dòng cài đặt được copy từ một bài viết trong June sẽ fail trên bản build trong July. Đây là lý do cần dùng --version trong command cài đặt và chỉ rõ một tag trong git clone, không phải vấn đề về phong cách.

Những việc tôi chưa sẵn sàng giao cho nó

Tính đến tháng 8 năm 2026, repository có khoảng 8.1k star, 1.2k fork và khoảng 350 issue đang mở; bản phát hành công khai đầu tiên mới được 7 tuần. Star cho biết mức độ quan tâm, không cho biết độ trưởng thành. Dự án tự mô tả là alpha, và lịch sử phát hành ở trên cho thấy đúng là alpha.

• Tôi sẽ không chạy nó trên host chứa credential production, vì sandbox chưa bao phủ MCP server hoặc supervisor.
• Tôi sẽ không để một run chạy mà không giám sát khi chưa có policy cost_budget, vì ba vendor có thể tính phí song song và không có cơ chế nào khác ngăn việc đó.
• Tôi sẽ không expose server trên địa chỉ IP public nếu chưa cấu hình OMNIGENT_AUTH_ENABLED và đặt TLS ở phía trước.
• Tôi chưa coi agent YAML là ổn định giữa các minor version, vì vậy hãy pin version và đọc release note trước khi nâng cấp.

Còn một điều bạn nên biết trước khi bị bất ngờ: v0.6.0 đã thêm telemetry ẩn danh về việc sử dụng, và dự án mô tả tính năng này trên một trang telemetry riêng. Hãy đọc trang đó và cân nhắc chủ động nếu máy này xử lý công việc của khách hàng.

Hiện tại, Omnigent thực sự làm tốt đúng việc mà nó được xây dựng để làm. Bạn có ba hoặc bốn agent CLI, đã trả phí cho chúng và muốn một agent viết trong khi agent khác review. Việc đó hiện đã hoạt động trên một máy, với sandbox thực sự trên Linux. Mọi khả năng vượt quá phạm vi đó vẫn còn nhiều triển vọng nhưng chưa hoàn thiện.

FAQ

Omnigent là agent hay là thứ chạy các agent?

Nó chạy các agent. Omnigent là một meta-harness: nó khởi chạy các vendor CLI mà bạn đã cài, chẳng hạn như Claude Code, Codex hoặc OpenCode, giao việc cho từng CLI rồi giám sát kết quả trong một session. Nó không có model riêng. Vì vậy, Omnigent khác framework, nơi bạn viết Python dựa trên một library và chính chương trình của bạn trở thành agent.

Tôi có cần cài Claude Code và Codex trước thì Omnigent mới hữu ích không?

Bạn cần cài và đăng nhập ít nhất một vendor CLI, vì Omnigent điều khiển các chương trình đó thay vì thay thế chúng. Với ví dụ Polly được cung cấp, bạn nên dùng từ hai vendor khác nhau trở lên. Polly luôn yêu cầu vendor thực hiện và vendor review phải khác nhau. Vì vậy, nếu chỉ có một CLI thì không có vendor thứ hai để nhận diff.

Làm thế nào để cài một phiên bản Omnigent cụ thể thay vì phiên bản mới nhất?

Truyền --version qua install script bằng sh -s --, như trong sh -s -- --version 0.7.0. Nếu không có -s --, sh sẽ tự xử lý flag này và script sẽ cài release mới nhất. Nếu đã có uv, uv tool install --force --python 3.12 "omnigent==0.7.0" thực hiện chức năng tương tự. Git tag là v0.7.0, còn chuỗi phiên bản trên PyPI là 0.7.0.

Omnibox sandbox có đủ để chạy các agent không cần giám sát không?

Nó bảo vệ tốt trong phạm vi được hỗ trợ và nêu rõ những gì không được hỗ trợ. Trên Linux, nó dùng bubblewrap cùng seccomp, nên kernel thực thi các giới hạn về file và network; agent không thể tự vô hiệu hóa các giới hạn này. Tài liệu nêu rằng cơ chế này áp dụng cho các lệnh gọi tool và terminal sys_os_*, nhưng không áp dụng cho MCP server hoặc tiến trình Omnigent supervisor. Vì vậy, MCP server chạy với quyền thông thường của bạn. Đây là lý do một virtual machine riêng cho mỗi agent vẫn là phương án isolation mạnh hơn khi chạy không cần giám sát.

Một server Omnigent trên VPS cần bao nhiêu memory?

Ghi chú deploy của dự án đưa ra working set khoảng 512 MB đến 1 GB cho server, còn cấu hình Fly.io cố định ở mức 1 GB. Mức này chỉ bao phủ supervisor và web interface trên port 6767. Mỗi sub-agent là một tiến trình riêng, có working copy và model client riêng. Các lần chạy kiểu Polly dùng nhiều git worktree song song. Vì vậy, hãy tính RAM và disk theo số agent bạn dự định chạy đồng thời, không chỉ theo server.