> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tich-hop/assistant/hermes-agent.md). # Hermes Agent Hướng dẫn tích hợp Hướng dẫn này trình bày cách kết nối Hermes với API tương thích OpenAI của AVIS, áp dụng cho cả **Hermes Agent CLI** và ứng dụng **Hermes Desktop**. ### Hermes là gì Hermes là agent lập trình và tự động hóa tác vụ mã nguồn mở của Nous Research. Công cụ có hai phiên bản: * **Hermes Agent (CLI)** — chạy trực tiếp trên terminal, qua `hermes chat`, `hermes -z "..."`, hoặc giao diện TUI qua `hermes --tui`. * **Hermes Desktop** — một ứng dụng giao diện đồ họa (macOS/Windows/Linux) bao bọc cùng lõi Hermes Agent: "cùng cấu hình, cùng API key, cùng phiên làm việc, cùng skill, cùng bộ nhớ." Cả hai phiên bản đều kết nối được với endpoint mô hình tương thích OpenAI và dùng mô hình/nhà cung cấp đã cấu hình để thực hiện các thao tác gọi công cụ (như sửa tệp và chạy lệnh shell). Trong hướng dẫn này, AVIS được đăng ký làm nhà cung cấp tùy chỉnh bằng cấu hình `provider: custom:avis`. Cấu hình dùng chung cho CLI và Desktop vì cả hai cùng đọc và ghi tệp `~/.hermes/config.yaml`. Các bước dưới đây (§1–5) hướng dẫn thiết lập AVIS một lần qua CLI. Mục §6 trình bày cách dùng cấu hình đó trong Hermes Desktop. ### 1) Yêu cầu * Shell trên macOS hoặc Linux * API key của AVIS Các giá trị tham chiếu dùng trong hướng dẫn này: * Base URL của AVIS: `https://api.avis.net/api/openai/v1` * AVIS API key: đặt qua biến môi trường ### 2) Cài đặt Hermes Agent Nếu chưa cài đặt Hermes: ```bash curl -fsSL https://get.hermes.nousresearch.com | bash ``` Kiểm tra cài đặt: ```bash hermes --version ``` Nếu `hermes` không có trong `PATH`, hãy chạy bằng đường dẫn đầy đủ: ```bash ~/.local/bin/hermes --version ``` ### 3) Đặt biến môi trường Đặt các giá trị AVIS trong shell hiện tại: ```bash export AVIS_BASE_URL="https://api.avis.net/api/openai/v1" export AVIS_API_KEY="" ``` Tùy chọn: lưu lại trong shell profile (`~/.zshrc` hoặc `~/.bashrc`). ### 4) Cấu hình nhà cung cấp và mô hình cho Hermes Tệp cấu hình của Hermes: ``` ~/.hermes/config.yaml ``` Mở tệp: ```bash open -a "Visual Studio Code" ~/.hermes/config.yaml ``` Thêm hoặc cập nhật các khối sau: ```yaml model: default: qwen3-7-plus provider: custom:avis providers: avis: name: Avis base_url: ${AVIS_BASE_URL} api_key: ${AVIS_API_KEY} discover_models: true model: qwen3-7-plus models: qwen3-7-plus: {} ``` Ghi chú: * `provider: custom:avis` nghĩa là Hermes sẽ dùng key nhà cung cấp `avis` trong `providers`. * Giữ `model.default`, `providers.avis.model` và `providers.avis.models.*` nhất quán với nhau. * Nếu máy chủ AVIS của bạn cung cấp model id khác, hãy thay `qwen3-7-plus` bằng giá trị đó. #### Cách khác: thiết lập tương tác Thay vì sửa tay `config.yaml`, `hermes model` có thể hướng dẫn bạn thêm endpoint tùy chỉnh theo kiểu tương tác: ```bash hermes model # Select "Custom endpoint (self-hosted / VLLM / etc.)" # Enter: API base URL, API key, Model name ``` Lệnh này ghi một khối kiểu `provider: custom:avis` giống hệt vào `config.yaml`, vì vậy cả hai cách đều cho ra cùng một tệp. #### Các key tùy chọn khác của nhà cung cấp Schema nhà cung cấp tùy chỉnh của Hermes hỗ trợ thêm một số trường ngoài những gì có trong khối trên — thêm chúng vào `providers.avis` nếu cần: | Key | Mục đích | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `context_length` | Tổng context window tính bằng token. Hermes yêu cầu **ít nhất 64K** khi dùng làm agent; hãy đặt rõ giá trị này nếu không thể tự động nhận diện AVIS/mô hình bên dưới hoặc giá trị mặc định thấp hơn. | | `max_tokens` | Giới hạn số token đầu ra cho mỗi phản hồi. | | `supports_vision` | Đặt `true` để bật định tuyến hình ảnh gốc nếu mô hình AVIS chấp nhận đầu vào hình ảnh. | | `headers` | Các HTTP header bổ sung gửi kèm mỗi request. | | `extra_body` | Các trường riêng của nhà cung cấp được gộp vào body của request. | | `key_env` | Tên biến môi trường chứa API key (ví dụ `key_env: AVIS_API_KEY`) — một cách thay thế cho việc ghi trực tiếp `api_key: ${AVIS_API_KEY}` nếu phiên bản Hermes của bạn ưu tiên tham chiếu gián tiếp hơn mở rộng kiểu shell. | Thứ tự tự động nhận diện context length: ghi đè trong cấu hình → cài đặt nhà cung cấp theo từng mô hình → kết quả khám phá đã cache → response `/v1/models` của máy chủ → các registry bên ngoài → giá trị dự phòng cố định. Nếu response `/models` của AVIS không công bố kích thước ngữ cảnh, hãy đặt rõ `context_length` để tránh Hermes âm thầm đặt thấp hơn hoặc cao hơn giá trị thực. ### 5) Chạy Hermes Chat Chế độ chat tương tác: ```bash hermes chat ``` Chế độ chạy một lần: ```bash hermes -z "hello from hermes" ``` Nếu cần, chạy với ghi đè rõ ràng nhà cung cấp/mô hình: ```bash hermes --provider custom:avis -m qwen3-7-plus -z "ping" ``` Khi đã cấu hình cả `custom:avis` và một nhà cung cấp khác, bạn có thể chuyển đổi giữa chúng ngay trong phiên mà không cần khởi động lại: ``` /model custom:avis:qwen3-7-plus ``` Lưu ý sự khác biệt: `hermes model` (bên ngoài phiên) đăng ký/sửa nhà cung cấp trong `config.yaml`; `/model` (bên trong phiên chat) chỉ chuyển đổi giữa các nhà cung cấp đã được cấu hình sẵn ở đó. Để thêm một nhà cung cấp hoàn toàn mới, hãy thoát phiên, chạy `hermes model`, rồi bắt đầu phiên mới. ### 6) Dùng AVIS trong Hermes Desktop Hermes Desktop là một ứng dụng giao diện đồ họa chạy cùng lõi Hermes Agent với CLI và dùng chung `~/.hermes/config.yaml` cùng thông tin xác thực — không có tài khoản hay kho cấu hình riêng nào cần đồng bộ. #### Cài đặt * Tải trình cài đặt từ website của Hermes, **hoặc** * Nếu đã cài CLI (§2), chỉ cần chạy: ```bash hermes desktop ``` #### Nếu AVIS đã được cấu hình qua CLI (§1–4) Không cần làm gì thêm — Hermes Desktop đọc cùng tệp `config.yaml`, nên `custom:avis` sẽ xuất hiện sẵn như một nhà cung cấp/mô hình khả dụng trong menu của ứng dụng ngay lần mở đầu tiên. #### Nếu thiết lập AVIS lần đầu trong Desktop Ở lần chạy đầu tiên, quá trình làm quen cho phép bạn chọn **Choose provider later** để vào thẳng ứng dụng, hoặc cấu hình nhà cung cấp ngay. Dù chọn cách nào, phần thiết lập nhà cung cấp nằm trong mục cài đặt **Providers** — một màn hình riêng để quản lý các nhà cung cấp inference (tài khoản, API key, endpoint tùy chỉnh). Thêm AVIS tại đó với cùng các giá trị như §1: * Base URL: `https://api.avis.net/api/openai/v1` * API key: AVIS API key của bạn * Model: model id AVIS của bạn (ví dụ `qwen3-7-plus`) Nếu mục Providers không có trường bạn cần (ví dụ `context_length` hoặc `key_env` trong bảng key tùy chọn ở §4), hãy sửa trực tiếp `~/.hermes/config.yaml` — Desktop nhận các thay đổi được thực hiện bên ngoài ứng dụng vì đó là cùng một tệp. ### 7) Khắc phục sự cố * `401 Unauthorized` * AVIS key không hợp lệ hoặc bị thiếu. * Kiểm tra lại `AVIS_API_KEY` và cách gửi header Authorization. * `404` hoặc không tìm thấy mô hình * Model id trong cấu hình Hermes không tồn tại trên `/models` của AVIS. * Đổi thành một model id thực do AVIS trả về. * Kết nối bị từ chối / hết thời gian chờ * URL bị sai (phải có `/api/openai/v1`). * Mạng/tường lửa đang chặn truy cập ra ngoài tới `api.avis.net`. * `hermes: command not found` * Dùng `~/.local/bin/hermes`. * Hoặc thêm nó vào `PATH`. * Agent hoạt động thất thường, cắt bớt ngữ cảnh hoặc từ chối đầu ra dài của tool * Hermes cần context window tối thiểu \~64K khi dùng làm agent. * Đặt rõ `providers.avis.context_length` (xem §4) nếu AVIS/mô hình bên dưới không được tự động nhận diện ở mức đó trở lên. * Mô hình xuất tool call dưới dạng văn bản thuần thay vì thực thi * Mô hình bên dưới mà AVIS đang chuyển tiếp tới có thể chưa bật tool-calling ở phía phục vụ (đây là vấn đề đã biết với các backend tự host như vLLM/llama.cpp/SGLang, vốn cần cờ tool-call-parser rõ ràng). * Xác nhận backend/mô hình AVIS có công bố hỗ trợ tool-calling; đây không phải điều có thể sửa từ phía cấu hình Hermes. ### 8) Danh sách kiểm tra tối thiểu từ đầu đến cuối 1. Đã export `AVIS_BASE_URL` và `AVIS_API_KEY`. 2. `~/.hermes/config.yaml` có cấu hình nhà cung cấp `custom:avis`. 3. `hermes chat` hoặc `hermes -z "..."` trả về kết quả từ mô hình. 4. (Desktop) `hermes desktop` khởi động và `custom:avis` xuất hiện trong Providers. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.avis.net/vi/tich-hop/assistant/hermes-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.