Hướng dẫn 26: Xử lý Hàng loạt | Easy Understand Hermes Agent

Đây là một phần trong loạt hướng dẫn chính thức của Hermes Agent. Xem tất cả hướng dẫn

Hãy nghĩ về điều này như một danh sách kiểm tra buổi sáng bạn chạy trước khi bắt đầu công việc — bạn không muốn phải tự mình nhớ từng nhiệm vụ, vì vậy bạn viết chúng ra một lần, và trợ lý của bạn sẽ tự động đánh dấu chúng mỗi ngày. Đó chính xác là những gì Hermes cho phép bạn làm với gateway hooks và một tệp tin đơn giản tên là BOOT.md.

Trong hướng dẫn này, bạn sẽ học cách làm cho Hermes chạy một “lô” tác vụ tùy chỉnh mỗi khi gateway của bạn khởi động — như kiểm tra nhật ký, đăng lời nhắc, hoặc thậm chí chạy một mini-agent có thể suy nghĩ và báo cáo lại.

Bước 1: Tạo thư mục hook của bạn

Đầu tiên, hãy tạo một thư mục bên trong thư mục hooks của bạn. Mỗi hook nằm trong thư mục con riêng của nó với hai tệp: HOOK.yaml (cấu hình) và handler.py (logic).

mkdir -p ~/.hermes/hooks/boot-md
cd ~/.hermes/hooks/boot-md

Bây giờ tạo HOOK.yaml:

name: "boot-md"
event: "gateway_startup"

Chỉ vậy thôi — sự kiện này báo cho Hermes kích hoạt hook này khi gateway khởi động.

Bước 2: Viết handler

Bây giờ tạo handler.py. Đây là nơi phép màu xảy ra. Handler đọc một tệp tên là BOOT.md từ thư mục chính của bạn, sau đó khởi động một luồng nền chạy một agent với những chỉ dẫn đó.

Đây là ý tưởng cốt lõi (được đơn giản hóa):

import os, threading
from pathlib import Path
from hermes.agent import AIAgent

def run_boot_md():
    content = Path.home().joinpath(".hermes", "BOOT.md").read_text()
    print(f"Running BOOT.md ({len(content)} chars)")

    agent = AIAgent(
        instructions=content,
        model=_resolve_gateway_model(),          # sử dụng model của gateway
        **_resolve_runtime_agent_kwargs()       # sử dụng thông tin xác thực của nhà cung cấp
    )
    result = agent.run()
    print(f"boot-md completed: {result.summary()}")

def handler(event):
    thread = threading.Thread(target=run_boot_md, daemon=True)
    thread.start()

Hai dòng quan trọng:

_resolve_gateway_model() đọc model hiện đang được cấu hình của gateway.
_resolve_runtime_agent_kwargs() giải quyết thông tin xác thực của nhà cung cấp giống như cách một lượt gateway bình thường làm — bao gồm API keys, base URLs, OAuth tokens và credential pools.

Nếu không có những thứ này, một AIAgent() trần sẽ rơi vào các mặc định tích hợp sẵn và sẽ trả về lỗi 401 với bất kỳ endpoint không mặc định nào.

Bước 3: Kiểm tra

Khởi động lại gateway:

hermes gateway restart

Xem nhật ký:

hermes logs --follow --level INFO | grep boot-md

Bạn sẽ thấy Running BOOT.md (N chars) theo sau là boot-md completed: ... (tóm tắt những gì agent đã làm) hoặc boot-md completed (nothing to report) khi agent trả lời bằng một token im lặng chính xác như [SILENT].

Xóa ~/.hermes/BOOT.md để vô hiệu hóa danh sách kiểm tra — hook vẫn được tải nhưng âm thầm bỏ qua khi tệp không tồn tại.

Mở rộng mẫu này

Danh sách kiểm tra theo lịch trình: dựa vào datetime.now().weekday() bên trong chỉ dẫn của BOOT.md (“nếu hôm nay là thứ Hai, hãy kiểm tra cả nhật ký triển khai hàng tuần”). Các chỉ dẫn là văn bản tự do, vì vậy bất cứ điều gì agent có thể suy luận đều có thể áp dụng.
Nhiều danh sách kiểm tra: trỏ hook đến một tệp khác (STARTUP.md, MORNING.md, v.v.) và đăng ký các thư mục hook riêng biệt cho từng tệp.
Biến thể không dùng agent: nếu bạn không cần một vòng lặp agent đầy đủ, hãy bỏ qua AIAgent hoàn toàn và để handler đăng một thông báo cố định trực tiếp qua httpx. Rẻ hơn, nhanh hơn và không phụ thuộc vào nhà cung cấp.

Tại sao đây không phải là tính năng tích hợp sẵn

Một phiên bản trước của Hermes đã đưa tính năng này vào như một hook tích hợp sẵn và âm thầm tạo ra một agent với các mặc định trần trên mỗi lần khởi động gateway. Điều đó gây bất ngờ cho người dùng có endpoint tùy chỉnh và khiến tính năng này trở nên vô hình với những người dùng không biết nó đang chạy. Giữ nó như một mẫu được ghi chép — do bạn tự xây dựng, trong thư mục hooks của bạn — nghĩa là bạn thấy chính xác những gì nó làm và chọn tham gia bằng cách viết các tệp tin.

Cách hoạt động

Khi gateway khởi động, HookRegistry.discover_and_load() quét ~/.hermes/hooks/
Mỗi thư mục con có HOOK.yaml + handler.py được tải động
Các handler được đăng ký cho các sự kiện đã khai báo của chúng
Tại mỗi điểm trong vòng đời, hooks.emit() kích hoạt tất cả các handler phù hợp
Lỗi trong bất kỳ handler nào đều được bắt và ghi lại — một hook bị lỗi không bao giờ làm sập agent

:::info Gateway hooks chỉ kích hoạt trong gateway (Telegram, Discord, Slack, WhatsApp, Teams). CLI không tải gateway hooks. Để có hooks hoạt động ở mọi nơi, hãy sử dụng plugin hooks. :::

Tóm tắt

Bạn giờ đã biết cách biến một tệp văn bản đơn giản thành một danh sách kiểm tra khởi động mạnh mẽ chạy tự động. Dù là một vòng lặp agent đầy đủ hay một lệnh gọi HTTP nhanh, mẫu này đều giống nhau: viết một hook, trỏ nó đến một tệp, và để Hermes lo phần còn lại.

Tiếp theo: Hướng dẫn 27 — Chế độ thoại: trò chuyện với Hermes rảnh tay.