บทเรียน 26: การประมวลผลแบบกลุ่ม

นี่เป็นส่วนหนึ่งของชุดบทช่วยสอนอย่างเป็นทางการของ Hermes Agent ดูบทช่วยสอนทั้งหมด

ลองนึกภาพว่านี่คือเช็กลิสต์ตอนเช้าที่คุณรันก่อนเริ่มงาน — คุณไม่อยากจำทุกงานเอง ดังนั้นคุณเขียนมันไว้ครั้งเดียว แล้วผู้ช่วยของคุณก็จะเช็คให้อัตโนมัติทุกวัน นั่นคือสิ่งที่ Hermes ให้คุณทำได้ด้วย gateway hooks และไฟล์ง่ายๆ ที่ชื่อว่า BOOT.md

ในบทช่วยสอนนี้ คุณจะได้เรียนรู้วิธีทำให้ Hermes รันชุดงาน “แบตช์” ที่กำหนดเองทุกครั้งที่ gateway ของคุณเริ่มทำงาน — เช่น การตรวจสอบล็อก การโพสต์การแจ้งเตือน หรือแม้แต่การรันมินิเอเจนต์ที่คิดและรายงานผลกลับมา

ขั้นตอนที่ 1: สร้างไดเรกทอรี hook ของคุณ

ก่อนอื่น ให้สร้างโฟลเดอร์ภายในไดเรกทอรี hooks ของคุณ แต่ละ hook จะอยู่ในโฟลเดอร์ย่อยของตัวเองพร้อมไฟล์สองไฟล์: HOOK.yaml (ไฟล์คอนฟิก) และ handler.py (ไฟล์ลอจิก)

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

จากนั้นสร้าง HOOK.yaml:

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

แค่นี้แหละ — อีเวนต์นี้จะบอกให้ Hermes เรียกใช้ hook นี้เมื่อ gateway บูตขึ้น

ขั้นตอนที่ 2: เขียน handler

ตอนนี้สร้าง handler.py นี่คือจุดที่ความมหัศจรรย์เกิดขึ้น handler จะอ่านไฟล์ชื่อ BOOT.md จากโฮมไดเรกทอรีของคุณ จากนั้นเริ่มเธรดพื้นหลังที่รันเอเจนต์พร้อมกับคำสั่งเหล่านั้น

นี่คือแนวคิดหลัก (แบบย่อ):

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(),          # ใช้โมเดลของ gateway ของคุณ
        **_resolve_runtime_agent_kwargs()       # ใช้ข้อมูลประจำตัวของผู้ให้บริการของคุณ
    )
    result = agent.run()
    print(f"boot-md completed: {result.summary()}")

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

สองบรรทัดสำคัญ:

_resolve_gateway_model() อ่านโมเดลที่ gateway กำลังใช้งานอยู่
_resolve_runtime_agent_kwargs() แก้ไขข้อมูลประจำตัวของผู้ให้บริการในลักษณะเดียวกับที่ gateway turn ทั่วไปทำ — รวมถึง API keys, base URLs, OAuth tokens และ credential pools

หากไม่มีสองบรรทัดนี้ AIAgent() เปล่าๆ จะถอยกลับไปใช้ค่าเริ่มต้นในตัวและจะเจอ error 401 เมื่อเชื่อมต่อกับ endpoint ที่ไม่ใช่ค่าเริ่มต้น

ขั้นตอนที่ 3: ทดสอบ

รีสตาร์ท gateway:

hermes gateway restart

ดูโลก็:

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

คุณควรเห็น Running BOOT.md (N chars) ตามด้วย boot-md completed: ... (สรุปสิ่งที่เอเจนต์ทำ) หรือ boot-md completed (nothing to report) เมื่อเอเจนต์ตอบกลับด้วยโทเคนความเงียบที่แน่นอน เช่น [SILENT]

ลบ ~/.hermes/BOOT.md เพื่อปิดการใช้งานเช็กลิสต์ — hook จะยังคงโหลดอยู่ แต่จะข้ามไปอย่างเงียบๆ เมื่อไม่มีไฟล์นั้น

การขยายรูปแบบ

เช็กลิสต์ที่รับรู้กำหนดการ: ใช้ datetime.now().weekday() ในคำสั่งของ BOOT.md (“ถ้าเป็นวันจันทร์ ให้ตรวจสอบล็อกการดีพลอยรายสัปดาห์ด้วย”) คำสั่งเป็นข้อความอิสระ ดังนั้นอะไรก็ตามที่เอเจนต์สามารถใช้เหตุผลได้ก็เป็นไปได้หมด
เช็กลิสต์หลายชุด: ชี้ hook ไปที่ไฟล์อื่น (STARTUP.md, MORNING.md ฯลฯ) และลงทะเบียนไดเรกทอรี hook แยกต่างหากสำหรับแต่ละไฟล์
รูปแบบที่ไม่ใช้เอเจนต์: หากคุณไม่ต้องการลูปเอเจนต์เต็มรูปแบบ ให้ข้าม AIAgent ไปเลย และให้ handler โพสต์การแจ้งเตือนแบบตายตัวโดยตรงผ่าน httpx ถูกกว่า เร็วกว่า และไม่พึ่งพาผู้ให้บริการ

ทำไมฟีเจอร์นี้ถึงไม่ได้เป็น built-in

Hermes เวอร์ชันก่อนหน้าเคยมาพร้อมกับฟีเจอร์นี้ในฐานะ built-in hook และจะสร้างเอเจนต์ด้วยค่าเริ่มต้นเปล่าๆ อย่างเงียบๆ ทุกครั้งที่ gateway บูต สิ่งนี้ทำให้ผู้ใช้ที่มี custom endpoints ประหลาดใจ และทำให้ฟีเจอร์นี้มองไม่เห็นสำหรับผู้ใช้ที่ไม่รู้ว่ามันทำงานอยู่ การเก็บไว้เป็นรูปแบบที่มีเอกสาร — สร้างโดยคุณ ในไดเรกทอรี hooks ของคุณ — หมายความว่าคุณเห็นชัดเจนว่ามันทำอะไร และเลือกใช้โดยการเขียนไฟล์ด้วยตัวเอง

วิธีการทำงาน

เมื่อ gateway เริ่มทำงาน HookRegistry.discover_and_load() จะสแกน ~/.hermes/hooks/
แต่ละไดเรกทอรีย่อยที่มี HOOK.yaml + handler.py จะถูกโหลดแบบไดนามิก
handler จะถูกลงทะเบียนสำหรับอีเวนต์ที่ประกาศไว้
ในแต่ละจุดของวงจรชีวิต hooks.emit() จะเรียกใช้ handler ที่ตรงกันทั้งหมด
ข้อผิดพลาดใน handler ใดๆ จะถูกจับและบันทึก — hook ที่เสียจะไม่ทำให้เอเจนต์คราฌ

:::info Gateway hooks จะทำงานเฉพาะใน gateway (Telegram, Discord, Slack, WhatsApp, Teams) เท่านั้น CLI จะไม่โหลด gateway hooks สำหรับ hooks ที่ทำงานได้ทุกที่ ให้ใช้ plugin hooks :::

สรุป

ตอนนี้คุณรู้วิธีเปลี่ยนไฟล์ข้อความง่ายๆ ให้เป็นเช็กลิสต์เริ่มต้นอันทรงพลังที่รันอัตโนมัติแล้ว ไม่ว่าจะเป็นลูปเอเจนต์เต็มรูปแบบหรือการเรียก HTTP แบบเร็วๆ รูปแบบก็เหมือนกัน: เขียน hook ชี้ไปที่ไฟล์ แล้วปล่อยให้ Hermes จัดการส่วนที่เหลือ