s00: Tổng quan về kiến trúc

Chương này là bản đồ cho toàn bộ repository.
Nếu tất cả những gì bạn muốn biết ngay bây giờ là "những mô-đun nào tạo nên hệ thống và tại sao tôi nên tìm hiểu chúng theo thứ tự này", hãy bắt đầu tại đây.

agent Hermes khác với các agent khác như thế nào

Hầu hết các hướng dẫn dành cho nhân viên đều dạy bạn cách xây dựng "một người trò chuyện với AI trong terminal".

agent Hermes thì khác. Ngay từ ngày đầu, nó đã được thiết kế như một agent tự trị đa nền tảng:

• Vòng lặp cốt lõi tương tự có thể hỗ trợ cuộc trò chuyện cuối cùng và đồng thời phục vụ Telegram, Discord, WeChat, Lark và hàng tá nền tảng khác
• Các lệnh đầu cuối không phải chạy cục bộ -- chúng có thể thực thi trong Docker, qua SSH trên máy từ xa hoặc trên đám mây
• agent có thể tạo và chỉnh sửa các tệp kỹ năng của riêng mình, không chỉ sử dụng các công cụ được xác định trước
• Cứ sau 10 lượt, agent sẽ tự động tạo một bản sao nền để xem lại cuộc trò chuyện, tự cập nhật bộ nhớ và kỹ năng -- một hệ thống tự tiến hóa vòng kín
• Tất cả các cuộc hội thoại được lưu giữ ở dạng SQLite với tính năng tìm kiếm toàn văn bản; không có gì bị mất khi khởi động lại
• Không khóa nhà cung cấp: Hơn 200 mô hình được hỗ trợ thông qua giao diện API tương thích với OpenAI
• Bộ sưu tập quỹ đạo hoàn chỉnh và quy trình đào tạo RL -- lịch sử hội thoại có thể được sử dụng trực tiếp để đào tạo mô hình thế hệ tiếp theo

Đây không phải là những tính năng được cố định sau thực tế. Họ đã định hình thiết kế cốt lõi ngay từ đầu.

Vì vậy, khi bạn nghiên cứu hệ thống này, bạn không nhìn vào "một vòng lặp đơn giản cộng với một túi dụng cụ". Bạn đang xem xét một kiến ​​trúc nền tảng với sự phân lớp rõ ràng.

repo này tái cấu trúc những gì

Những gì repo này thực sự nhằm mục đích xây dựng lại là:

• Các lớp cốt lõi của Hermes Agent là gì
• Tại sao mỗi lớp tồn tại
• Điều gì xảy ra giữa thời điểm người dùng gửi tin nhắn và thời điểm nhân viên trả lời
• Nơi trạng thái quan trọng tồn tại
• Quyết định thiết kế nào cho phép nó phục vụ nhiều nền tảng cùng một lúc

Mục tiêu của chúng tôi:

Xây dựng lại các quyết định thiết kế và phân lớp kiến trúc dành riêng cho agent Hermes, thay vì cung cấp các hướng dẫn chung về agent.

Ba nguyên tắc đọc

1. Bắt đầu với CLI, sau đó chuyển sang Cổng

agent Hermes có hai điểm vào: terminal tương tác (CLI) và cổng đa nền tảng (Gateway).

Bạn không cần phải học cả hai cùng một lúc. Giai đoạn 1 và 2 chỉ bao gồm điểm vào CLI. Cổng không được giới thiệu cho đến Giai đoạn 3.

Điều này hiệu quả vì CLI và Gateway cuối cùng gọi cùng một vòng lặp lõi. Làm chủ vòng lặp lõi trước và cắm vào nhiều nền tảng sau chỉ là "hoán đổi nguồn tin nhắn".

2. Bắt đầu với Thực thi cục bộ, sau đó chuyển sang nhiều phần phụ trợ

Logic tương tự. Các lệnh đầu cuối có thể chạy trong Docker, qua SSH hoặc trên đám mây, nhưng Giai đoạn 1 chỉ bao gồm việc thực thi cục bộ.

Khi bạn hiểu được đường dẫn đầy đủ thông qua hệ thống công cụ, việc thêm tính trừu tượng hóa môi trường thực thi chỉ là "hoán đổi vị trí lệnh chạy".

3. Xây dựng phiên bản tối thiểu trước tiên; Dừng lại ở ranh giới giảng dạy

Mỗi chương đều bắt đầu với việc triển khai tối thiểu nhưng chính xác, sau đó cho bạn biết "bạn sẽ thêm những gì nếu tiếp tục lặp lại".

Đừng cố gắng tiếp thu tất cả sự phức tạp trong một lần.

Kiến trúc năm lớp của agent Hermes

Đây là điều khiến agent Hermes khác biệt so với hầu hết các hướng dẫn về agent: nó không phải là "một vòng lặp + một túi công cụ" mà là một hệ thống có năm lớp riêng biệt.

+-------------------------------------+
| Entry Layer                         |
| Where does the user come from?      |
| CLI / Telegram / Discord / WeChat / ... |
+----------------+--------------------+
                 |
                 v
+-------------------------------------+
| Core Loop Layer                     |
| Model thinks -> call tools ->       |
| write results back -> continue      |
| Synchronous loop; async tools       |
| bridged via an event loop           |
+----------------+--------------------+
                 |
                 v
+-------------------------------------+
| Tool & Intelligence Layer           |
| Self-registering tools / memory /   |
| skills / approval gates             |
| Adding a tool never touches the     |
| core loop                           |
+----------------+--------------------+
                 |
                 v
+-------------------------------------+
| Execution Environment Layer         |
| Where do commands run?              |
| Local / Docker / SSH / Cloud        |
+----------------+--------------------+
                 |
                 v
+-------------------------------------+
| Persistence Layer                   |
| SQLite sessions / MEMORY.md /       |
| skill files                         |
| Conversations and knowledge survive |
| across restarts                     |
+-------------------------------------+

Tại sao có năm lớp này

Lớp nhập: Hầu hết các agent đều có một điểm vào cuối duy nhất. agent Hermes có hai -- CLI và Cổng. Bên trong Gateway có hơn chục bộ điều hợp nền tảng. Công việc của lớp đầu vào là chuẩn hóa các tin nhắn từ các nguồn khác nhau thành một định dạng thống nhất và chuyển chúng đến vòng lặp lõi.

Lớp vòng lặp lõi: Đây là trái tim của hệ thống. Bất kể tin nhắn đến từ đâu, nó đều đi vào cùng một vòng lặp: gửi tới mô hình -> xử lý lệnh gọi công cụ -> ghi lại kết quả -> tiếp tục. Vòng lặp là đồng bộ. Các công cụ không đồng bộ (chẳng hạn như yêu cầu mạng) được kết nối thông qua vòng lặp sự kiện liên tục thay vì làm cho toàn bộ vòng lặp không đồng bộ.

Lớp công cụ & thông minh: Công cụ không phải là các lệnh gọi hàm nằm rải rác trên cơ sở mã. Chúng tạo thành một hệ thống tự đăng ký -- mỗi tệp công cụ sẽ tự động đăng ký khi nhập. Trí nhớ, kỹ năng và phê duyệt lệnh nguy hiểm cũng nằm trong lớp này. Họ không sửa đổi mã của vòng lặp lõi; thay vào đó, họ chèn logic trước và sau lệnh gọi công cụ.

Lớp môi trường thực thi: Các lệnh đầu cuối không cần phải chạy cục bộ. Hermes Agent tóm tắt giao diện môi trường thực thi với sáu cách triển khai: local, Docker, SSH, Modal, Daytona và Singularity. Các công cụ lớp trên không cần biết lệnh chạy ở đâu.

Lớp kiên trì: Lịch sử hội thoại tồn tại trong SQLite (không phải tệp phẳng), hỗ trợ đọc/ghi đồng thời và tìm kiếm toàn văn bản. Bộ nhớ tồn tại trong MEMORY.md / USER.md. Kỹ năng tồn tại trong một thư mục kỹ năng. Tất cả trạng thái này vẫn tồn tại trong quá trình khởi động lại.

Cách tin nhắn truyền qua hệ thống

Lấy kịch bản CLI làm ví dụ (đường dẫn đơn giản nhất):

1. User types a message in the terminal
2. CLI creates an AIAgent instance
3. AIAgent assembles the system prompt
   - Read SOUL.md (persona)
   - Read MEMORY.md / USER.md (memory)
   - Read HERMES.md or AGENTS.md (project configuration)
   - Append tool definitions and skill index
4. Send messages + system prompt + tools to the model API
   (via the OpenAI SDK; all providers use the same interface)
5. Model returns:
   - If plain text -> display to user, done
   - If tool_calls -> continue
6. For each tool_call:
   - Look up the handler in the tool registry
   - Check whether it matches a dangerous-command pattern
   - Execute the tool (in the current execution environment)
   - Write the result back into messages with role "tool"
7. Go back to step 4 for the next iteration
8. After the loop ends, persist the entire session to SQLite

Lấy kịch bản Cổng làm ví dụ (thêm lớp định tuyến tin nhắn):

1. User sends a message in Telegram
2. The Telegram adapter receives the message and converts it to the unified format
3. Gateway looks up or creates a session based on chat_id
4. Gateway creates an AIAgent instance (passing in historical messages)
5. The remaining steps are identical to CLI (steps 3-8)
6. The agent's reply is sent back to the user through the Telegram adapter

Thông tin chi tiết chính: Sự khác biệt duy nhất giữa kịch bản Cổng và kịch bản CLI là điểm vào và điểm thoát; vòng lặp lõi hoàn toàn giống nhau.

Năm quyết định thiết kế quan trọng trong agent Hermes

Năm quyết định này là chìa khóa để hiểu hệ thống. Nếu không nắm bắt được chúng, các chương sau sẽ khiến bạn thắc mắc "tại sao nó lại được thực hiện theo cách này?"

1. Tại sao nên sử dụng OpenAI SDK làm Ứng dụng khách API duy nhất

agent Hermes không bị khóa đối với bất kỳ nhà cung cấp mô hình nào. Nó sử dụng SDK Python OpenAI (from openai import OpenAI) và kết nối với các nhà cung cấp khác nhau bằng cách cài đặt khác nhau base_url các giá trị.

Điều này có nghĩa là việc chuyển từ OpenRouter sang Anthropic hoặc điểm cuối cục bộ không yêu cầu thay đổi mã -- chỉ là cập nhật cấu hình.

Quyết định này quy định định dạng tin nhắn cho toàn bộ hệ thống: tất cả tin nhắn đều sử dụng định dạng OpenAI (role: user/assistant/tool, tool_calls, tool_call_id).

2. Tại sao vòng lặp lõi lại đồng bộ

Hầu hết các khung Python hiện đại đều nghiêng về hướng hoàn toàn không đồng bộ. Nhưng vòng lặp cốt lõi trong Hermes Agent là một vòng lặp đồng bộ def run_conversation(), không phải một async def.

Những lý do rất thực tế:

• Hầu hết các công cụ (tệp I/O, lệnh đầu cuối) vốn đã đồng bộ
• Việc xử lý lỗi và gỡ lỗi đơn giản hơn nhiều trong vòng lặp đồng bộ
• Một số công cụ không đồng bộ (yêu cầu mạng) được kết nối thông qua vòng lặp sự kiện liên tục

Mẫu "thân đồng bộ + cầu không đồng bộ" này chạy qua toàn bộ lớp công cụ.

3. Tại sao các công cụ sử dụng tính năng Tự đăng ký thay vì Cấu hình trung tâm

Mỗi tệp công cụ sẽ tự động gọi đến sổ đăng ký register() phương pháp nhập Python.

Chuỗi nhập rõ ràng: sổ đăng ký không phụ thuộc vào công cụ nào -> công cụ phụ thuộc vào sổ đăng ký -> lớp điều phối nhập tất cả các công cụ để kích hoạt đăng ký -> vòng lặp lõi sử dụng lớp điều phối.

Điều này có nghĩa là việc thêm một công cụ mới chỉ yêu cầu ghi một tệp; không có tập tin nào khác cần thay đổi.

4. Tại sao SQLite thay vì Hệ thống tệp

Bởi vì trong kịch bản Cổng, tin nhắn từ nhiều nền tảng có thể đến đồng thời. Chế độ WAL của SQLite hỗ trợ đọc và ghi đồng thời và FTS5 cho phép tìm kiếm toàn văn bản qua các phiên lịch sử.

Cách tiếp cận hệ thống tệp hoạt động tốt khi sử dụng CLI một người dùng, nhưng bị hỏng khi hoạt động đồng thời trên nhiều nền tảng.

5. Tại sao agent có thể tự sửa đổi

Đây là điểm khác biệt cơ bản nhất giữa Hermes Agent và các framework như LangChain hay AutoGen: agent không chỉ có thể thực thi các nhiệm vụ mà còn có thể học hỏi kinh nghiệm và viết lại hành vi của chính mình.

Điều này được thể hiện qua ba cơ chế:

• Đánh giá cơ bản: Mỗi lần N cuộc trò chuyện, nhân viên chính sẽ tạo ra một bản sao cơ bản với công việc duy nhất là hỏi "có sở thích nào của người dùng đáng ghi nhớ không? Có giải pháp nào đáng để trừu tượng hóa thành kỹ năng không?" -- không cần người dùng nhắc nhở, nó tự động cập nhật MEMORY.md/USER.md hoặc tạo các kỹ năng mới
• Vòng tác giả kỹ năng: agent có thể trực tiếp tạo, chỉnh sửa và vá các tệp kỹ năng của riêng mình thông qua skill_manager_tool. Lần tiếp theo gặp một nhiệm vụ tương tự, nó sẽ sử dụng lại kỹ năng đó thay vì lý luận từ đầu
• Quỹ đạo + Đường ống RL: Tất cả quỹ đạo hội thoại có thể được nén thành dữ liệu huấn luyện và được sử dụng để đào tạo RL cho mô hình thế hệ tiếp theo

Hai cơ chế đầu tiên hoạt động trong runtime ("học tập"); thứ ba hoạt động ngoại tuyến ("tiến hóa"). Chúng cùng nhau tạo thành một vòng khép kín hoàn chỉnh: sử dụng -> ghi nhớ -> trừu tượng -> đào tạo -> sử dụng tốt hơn.

Giai đoạn 5 trình bày chi tiết về vòng lặp này.

Lộ trình học tập năm giai đoạn

Sau mỗi giai đoạn, hãy tạm dừng và viết tay một phiên bản tối thiểu từ bộ nhớ trước khi tiếp tục.

Giai đoạn 5: Các chương dành riêng

Đây là phần mà hầu hết các hướng dẫn về agent không bao giờ đề cập đến -- điểm khác biệt thực sự của agent Hermes:

• s20: Đánh giá cơ bản -- Cách nhân viên xem xét nội tâm, định kỳ thực hiện quy trình tự đánh giá
• s21: Vòng lặp tác giả kỹ năng -- Cách agent đọc và ghi các tệp kỹ năng của riêng mình, biến các giải pháp một lần thành các khả năng có thể tái sử dụng
• s22: Hook System và BOOT.md -- Thúc đẩy sự thích ứng liên tục thông qua các hook trong vòng đời: tự kiểm tra khi khởi động, tóm tắt vào cuối phiên
• s23: Vòng huấn luyện quỹ đạo và RL -- batch_runner + trajectory_compressor + rl_cli: dữ liệu hội thoại trở thành dữ liệu đào tạo như thế nào
• s24: Kiến trúc plugin và Hệ sinh thái nhà cung cấp bộ nhớ -- hình ba chiều, honcho, mem0, supermemory và các phần phụ trợ bộ nhớ có thể cắm khác

Trạng thái quan trọng bạn cần hiểu

tin nhắn -- Bộ nhớ làm việc

Tất cả tin nhắn trong cuộc trò chuyện hiện tại. Đây không phải là màn hình hiển thị nhật ký trò chuyện -- đây là thông tin đầu vào mà mô hình sẽ đọc ở lượt tiếp theo.

Sổ đăng ký công cụ - Thư mục khả năng

Ánh xạ từ "tên công cụ -> hàm xử lý." Công cụ tự đăng ký; khi chạy, các cuộc gọi được gửi đi bằng cách tra cứu bảng.

Phiên SQLite - Bản ghi liên tục

Toàn bộ siêu dữ liệu phiên và lịch sử tin nhắn. Toàn văn có thể tìm kiếm được, an toàn đồng thời.

SOUL.md / MEMORY.md / HERMES.md -- Bối cảnh dài hạn

Ba nguồn bối cảnh dài hạn khác nhau: tính cách, trí nhớ và cấu hình dự án. Chúng được tập hợp thành lời nhắc của hệ thống khi bắt đầu mỗi cuộc trò chuyện.

Môi trường thực thi - Nơi lệnh chạy

Một giao diện trừu tượng, trong suốt đối với các lớp trên. Các công cụ không quan tâm lệnh chạy cục bộ hay bên trong Docker.

Nơi người đọc bị mắc kẹt thường xuyên nhất

"Chính xác thì mối quan hệ giữa Gateway và CLI là gì?"

Chúng là hai điểm vào khác nhau vào cùng một vòng lặp lõi. Tìm hiểu CLI trước; hãy nhìn vào Gateway ở Giai đoạn 3.

"Công cụ, kỹ năng và MCP đều là khả năng -- có gì khác biệt?"

• Công cụ: khả năng được mã hóa cứng trong nguồn
• Kỹ năng: các tệp khả năng mà agent có thể tạo và chỉnh sửa khi chạy
• MCP: khả năng của bên thứ ba được kết nối thông qua giao thức bên ngoài

"Tại sao có nhiều nguồn cấu hình như vậy?"

Bởi vì agent có thể chạy trong các kịch bản khác nhau (phát triển CLI, sản xuất Telegram, cách ly Docker) và mỗi kịch bản cần có các cài đặt khác nhau. Hệ thống cấu hình hợp nhất nhiều nguồn bằng chuỗi ưu tiên.

Đi đâu từ đây

Thứ tự đọc khuyến nghị:

1. Bắt đầu với s01 (vòng lặp agent) và s02 (hệ thống công cụ) -- agent khả thi tối thiểu
2. Sau đó s03 thông qua s06 -- thêm tính bền vững, lắp ráp prompt, nén, xử lý lỗi
3. Di chuyển đến s07 thông qua s11 -- thêm bộ nhớ, kỹ năng, an toàn, ủy quyền, cấu hình
4. Tiếp tục với s12 thông qua s15 - nhập lãnh thổ đa nền tảng
5. Sau đó s16 thông qua s19 -- các khả năng nâng cao và các lớp giao diện
6. Cuối cùng s20 thông qua s24 -- vòng lặp tự tiến hóa và kiến trúc có thể mở rộng

Nếu bạn chỉ muốn một "agent làm việc" thì việc hoàn thành Giai đoạn 1-2 là đủ. Nếu bạn muốn kết nối các nền tảng nhắn tin, hãy đọc qua Giai đoạn 3. Nếu bạn muốn hiểu điều gì khiến agent Hermes trở nên đặc biệt -- bạn phải đọc qua Giai đoạn 5.

Nếu thuật ngữ bắt đầu gặp rắc rối ở bất kỳ chương nào, hãy quay lại chương này và glossary.md để bồi dưỡng.

---

Một câu cần nhớ:

Thiết kế cốt lõi của Hermes Agent là "vòng agent đồng bộ + hệ thống công cụ tự đăng ký + tính bền bỉ của SQLite." Lõi này kết nối với nhiều nền tảng thông qua Cổng, thực thi trên nhiều chương trình phụ trợ thông qua tính năng trừu tượng hóa môi trường và hình thành vòng lặp tự phát triển thông qua Đánh giá lý lịch + Tác giả kỹ năng + Đào tạo RL.