Omnigent: chạy nhiều agent CLI trong một harness

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) mà bạn đã cài đặt. 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 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 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 đó, cùng một agent sẽ 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 từng agent.

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 của bạn, 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 nó, đăng nhập và nó tự hoạt động.

Framework là một thư viện để bạn viết code dựa trên đó. Bạn import thư viện, định nghĩa các bước trong 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 trực tiếp vào chương trình.

Meta-harness nằm ở cấp cao hơn cả hai. Đây là một supervisor chạy các harness dưới dạng tiến trình con. Omnigent khởi động vendor CLI, 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, cùng subscription hoặc API (application programming interface) key đang dùng để thanh toán. Đó là toàn bộ khác biệt. Khác biệt này cũng xác định tool dành cho ai: những người đã có nhiều agent CLI hoạt động ổn định nhưng mệt mỏi vì phải điều khiển từng CLI trong từng terminal riêng lẻ.

Lớp orchestration duy nhất giải quyết vấn đề gì?

• Đổ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 chéo giữa các vendor. Một model viết diff sẽ được model của công ty khác đọc lại. Hai model cùng một họ thường có chung điểm mù, nên ý kiến thứ hai từ cùng một vendor có giá trị thấp hơn.
• Policy có một nơi khai báo duy nhất. Giới hạn chi phí và prompt yêu cầu phê duyệt được khai báo trong file agent, đồng thời áp dụng cho mọi sub-agent bên dưới agent đó.
• 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ể đọc lại những gì đã xảy ra mà không phải ghép bốn màn hình cuộn với nhau.

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

Vị trí của multi-agent harness bên cạnh 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; Omnigent giả định bạn đã có sẵn thiết lập này. Lĩnh vực rộng hơn về self-hosted AI agent là nơi bạn chọn các agent, còn tìm hiểu cách agent thực sự hoạt động sẽ phù hợp hơn nếu các thuật ngữ ở đây còn mới với bạn.

Omnigent cũng hoạt động trên một phương diện khác với connector layer. Nội dung như cho agent truy cập các nguồn dữ liệu của bạn liên quan đến những gì agent có thể truy cập. Omnigent tập trung vào việc agent nào chạy, chạy theo thứ tự nào và chịu các 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.

Điều kiện cần có trước khi cài đặt

• Python 3.12 trở lên. Gói đã phát hành khai báo requires-python >= 3.12.
• tmux, vì các harness chạy trong đó.
• Ít nhất một CLI của nhà cung cấp đã đượ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 assets đã 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 release được ghim, không cài 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 của chính nó, còn trình cài đặt không bao giờ nhận được flag đó. Kết quả là bạn sẽ nhận bản mới nhất tại thời điểm chạy lệnh. Với một repository phát hành các thay đổi gây lỗi tương thích 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 cấu hình và một sự cố bất ngờ.

Trình cài đặt sử dụng uv, trình quản lý package Python của Astral, và đề nghị cài uv trước nếu máy 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 extras cũng dùng cùng mẫu này và flag được lặp lại: --extra e2b --extra kubernetes trên script, hoặc "omnigent[e2b,kubernetes]" khi dùng 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 trả về, thường là ~/.local/bin, và trình cài đặt đề nghị thêm thư mục đó vào shell profile. Nếu lệnh không được tìm thấy ngay sau khi cài mới, đó là nguyên nhân. Kiểm tra phiên bản thực tế đang có:

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 được 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 nhà cung cấp model

omni setup

Trình hướng dẫn tìm các thông tin xác thực đã có trong môi trường và yêu cầu bạn nhập những thông tin còn thiếu. Nó hỗ trợ API key, gói thuê bao của nhà cung cấp, 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ỏ gateway đến server đó để traffic không bao giờ rời khỏi máy.

Chạy multi-agent tối thiểu

Các agent mẫu nằm trong repository. 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à orchestrator lập trình multi-agent được phát hành cùng 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 rule 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 bên 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 mục cho agent và chuyển từng diff đến reviewer thuộc vendor khác.

Trước khi giao bất kỳ việc nào, Polly chạy preflight check để 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, ví dụ còn lại được phát hành cùng repository, là một debate agent có hai head, một Claude và một GPT:

omni debby

Đây là cách nhanh để xác nhận hai provider đã được cấu hình, vì Debby cần cả hai provider để tạo ra bất kỳ output nào.

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

File agent dùng YAML. executor chứa tên harness, model và thông tin xác thực. tools chứa các MCP (model context protocol) server, 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à các tên do 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 sử dụng generic protocol. Spec cũng hỗ trợ pass_history: true trên sub-agent. Tùy chọn này truyền conversation của parent cho sub-agent. Mỗi lần delegation đều tốn thêm token, vì vậy hãy tắt tùy chọn này với các sub-agent chỉ cần task hiện tại. Nếu prompt của coder yêu cầu coder thực hiện thay đổi nhỏ nhất nhưng vẫn hoạt động, coder sẽ gửi cho reviewer một diff đủ ngắn để đọc thực sự. Trong trường hợp này, điều đó quan trọng hơn model được chọn cho từng role.

Vì sao orchestration chạy lâu nên được thực hiện 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 phải lập kế hoạch, giao việc, chờ các git worktree chạy song song, review rồi 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 host web user interface trên port 6767. omnigent server status cho biết có một phiên đang chạy hay không, còn omnigent stop sẽ dừng phiên đó. Trước bản phát hành v0.7.0, lệnh này là omni server start nhưng đã bị xóa, nên các bài viết và ảnh chụp màn hình cũ sẽ không khớp với kết quả trên terminal của bạn.

Không publish port 6767 trên địa chỉ public. Có hai cách cấu hình an toàn. Giữ port đóng trên firewall và forward port đó 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 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 phía trước nhiều ứng dụng Docker Compose thì Omnigent chỉ là thêm một service theo cùng mô hình.

Khi deploy bằng container, thư mục deploy/ trong 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 đặt giá trị là 1 bên trong các container. Đây là giá trị mặc định phù hợp cho mọi thứ có thể truy cập từ bên ngoài.

Về sizing, ghi chú deploy ước tính working set của server vào khoảng 512 MB đến 1 GB, còn cấu hình Fly.io cố định ở mức 1 GB. Con số này 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 hãy sizing server 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ẽ register 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 bạn rời máy

Omnigent cung cấp một 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 thay vì prompt của agent. Agent bị chèn prompt không thể dùng lời lẽ để vượt qua một 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: []

Thư mục làm việc ở 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 nêu tên trong cwd_allow_hidden. Vì vậy, một quyền đọc rộng không âm thầm để lộ .ssh hoặc .aws. Đặt egress_rules để toàn bộ lưu lượng HTTP và HTTPS đi qua một proxy mặc định từ chối, với mỗi rule được viết theo dạng "METHODS host/path-glob". credential_proxy còn đi xa hơn: agent chỉ giữ một placeholder, còn proxy thay bằng secret thật khi request rời hệ thống. Vì vậy, transcript bị lộ cũng không làm lộ secret có thể sử dụng. Trong một 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ờ đó, reviewer có thể bị chặn network trong khi implementer vẫn được phép sử dụng network.

Tài liệu đã nêu rõ giới hạn này và bạn cần lưu ý. OS sandbox áp dụng cho các lệnh gọi tool sys_os_* và terminal. Nó không bao phủ MCP server, cũng không bao phủ chính tiến trình supervisor của Omnigent. MCP server mà bạn khởi động sẽ chạy bên ngoài sandbox với quyền của bạn. Khoảng trống này là lý do pattern an toàn hơn vẫn là dùng một máy dùng một lần cho mỗi agent. Nội dung đó được trình bày trong chạy coding agent trong VM dùng một lần. Nửa công việc còn lại là credential. Việc giữ secret ngoài tầm với của agent sẽ khó hơn, không dễ hơn, khi sáu sub-agent dùng chung một host.

Giới hạn chi tiêu 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 với vendor thứ nhất, triển khai với vendor thứ hai và review với 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 run unattended đầu tiên, thay vì đợi đến sau invoice đầu tiên. Các tính năng tích hợp cũng bao gồm max_tool_calls_per_session và ask_on_os_tools. Tính năng 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àng quan trọng hơn vì các sub-agent chạy song song sẽ nhân tốc độ tiêu tiền.

Kho lưu trữ này thay đổi 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 copy từ một bài viết vào June sẽ fail trên bản build vào July. Đây là lý do cần dùng --version trong install command và chỉ định một tag trong git clone, không phải vấn đề về phong cách.

Những việc hiện chưa nên giao cho nó

Tính đến tháng 8 năm 2026, repository này 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. Số star chỉ phản ánh mức độ quan tâm, không phản ánh độ trưởng thành. Dự án tự ghi là alpha, và lịch sử phát hành ở trên cho thấy alpha ở đây đúng là alpha.

• Tôi sẽ không chạy nó trên host chứa credential production, vì sandbox không bao phủ MCP server hoặc supervisor.
• Tôi sẽ không để một run chạy không giám sát nếu 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.
• Hiện tôi chưa xem 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ó một điều nữa bạn nên biết để tránh bị bất ngờ: v0.6.0 bổ sung telemetry sử dụng đã ẩn danh, và dự án ghi chép nội dung này trên một trang telemetry riêng. Hãy đọc trang đó và cân nhắc có chủ đích nếu máy này xử lý công việc của khách hàng.

Điểm Omnigent thực sự làm tốt hiện nay chính là mục đích ban đầu của nó. 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. Hãy xem mọi thứ vượt quá phạm vi đó là có tiềm năng nhưng chưa hoàn thiện.

FAQ

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

Omnigent chạy các agent. Omnigent là một meta-harness: nó khởi chạy các vendor CLI bạn đã cài, chẳng hạn như Claude Code, Codex hoặc OpenCode, giao việc cho từng CLI và giám sát kết quả trong một session. Omnigent không có model riêng. Vì vậy, nó khác với framework, nơi bạn viết Python dùng một library và 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 phát hành kèm, 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, sẽ không có vendor thứ hai để nhận diff.

Làm cách 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 --, chính sh sẽ nhận flag này và script sẽ cài release mới nhất. Khi đã có uv, uv tool install --force --python 3.12 "omnigent==0.7.0" thực hiện cùng tác vụ. 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 agent không cần giám sát không?

Sandbox này mạnh trong phạm vi nó hỗ trợ và nêu rõ những gì nó không bao phủ. 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, đồng thời agent không thể tự vô hiệu hóa các giới hạn đó. Tài liệu cho biết sandbox áp dụng cho các tool call và terminal sys_os_*, nhưng không áp dụng cho MCP server hoặc tiến trình supervisor của Omnigent. Vì vậy, MCP server chạy với quyền thông thường của bạn. Đây là lý do dùng một virtual machine có thể bỏ đi cho mỗi agent vẫn là cách 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 bộ nhớ?

Ghi chú triển khai của dự án cho biết server cần working set khoảng 512 MB đến 1 GB, 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.