튜토리얼 26: 배치 처리 | Easy Understand Hermes Agent

이 글은 Hermes Agent 공식 튜토리얼 시리즈의 일부입니다. 전체 튜토리얼 보기

이건 출근 전에 실행하는 아침 체크리스트라고 생각하면 됩니다. 모든 할 일을 매번 기억하고 싶지 않으니까 한 번 적어두고, 비서가 매일 자동으로 확인해 주는 거죠. Hermes에서도 게이트웨이 훅(gateway hooks) 과 BOOT.md라는 간단한 파일로 정확히 그렇게 할 수 있습니다.

이 튜토리얼에서는 게이트웨이가 시작될 때마다 Hermes가 커스텀 “배치(batch)” 작업을 실행하도록 만드는 방법을 배웁니다. 로그 확인, 리마인더 게시, 또는 생각하고 보고하는 미니 에이전트 실행까지 가능합니다.

1단계: 훅 디렉토리 만들기

먼저 훅 디렉토리 안에 폴더를 만듭니다. 각 훅은 HOOK.yaml(설정)과 handler.py(로직) 두 개의 파일이 있는 하위 폴더에 위치합니다.

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

이제 HOOK.yaml을 생성합니다:

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

끝입니다. 이 이벤트는 게이트웨이가 부팅될 때 이 훅을 실행하라고 Hermes에 알려줍니다.

2단계: 핸들러 작성하기

이제 handler.py를 만듭니다. 여기서 마법이 일어납니다. 핸들러는 홈 디렉토리에서 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(),          # 게이트웨이의 모델 사용
        **_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()은 게이트웨이에 현재 설정된 모델을 읽어옵니다.
_resolve_runtime_agent_kwargs()는 일반 게이트웨이 턴과 동일한 방식으로 프로바이더 자격 증명을 해석합니다. API 키, base URL, OAuth 토큰, 자격 증명 풀을 포함합니다.

이것들이 없으면 기본 AIAgent()는 내장 기본값으로 폴백되어 기본이 아닌 엔드포인트에서 401 오류가 발생합니다.

3단계: 테스트하기

게이트웨이를 재시작합니다:

hermes gateway restart

로그를 확인합니다:

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

Running BOOT.md (N chars)가 표시되고, 이어서 에이전트가 수행한 작업의 요약인 boot-md completed: ... 또는 에이전트가 [SILENT] 같은 정확한 침묵 토큰으로 응답한 경우 boot-md completed (nothing to report)가 표시되어야 합니다.

~/.hermes/BOOT.md를 삭제하면 체크리스트가 비활성화됩니다. 훅은 계속 로드되어 있지만 파일이 없으면 조용히 건너뜁니다.

패턴 확장하기

일정 인식 체크리스트: BOOT.md 지침 안에서 datetime.now().weekday()를 활용합니다(“월요일이면 주간 배포 로그도 확인”). 지침은 자유 형식 텍스트이므로 에이전트가 추론할 수 있는 모든 것이 가능합니다.
여러 체크리스트: 훅이 다른 파일(STARTUP.md, MORNING.md 등)을 가리키도록 하고 각각 별도의 훅 디렉토리를 등록합니다.
에이전트 없는 변형: 전체 에이전트 루프가 필요 없다면 AIAgent를 완전히 건너뛰고 핸들러가 httpx를 통해 고정 알림을 직접 게시하면 됩니다. 더 저렴하고 빠르며 프로바이더 의존성도 없습니다.

왜 내장 기능이 아닌가?

이전 버전의 Hermes는 이 기능을 내장 훅으로 제공했고, 게이트웨이가 부팅될 때마다 기본 설정으로 에이전트를 조용히 생성했습니다. 이로 인해 커스텀 엔드포인트를 사용하는 사용자에게 혼란을 주었고, 실행 중인지도 모르는 사용자에게는 기능이 보이지 않았습니다. 문서화된 패턴으로 유지하고 — 여러분이 직접 훅 디렉토리에 만들고 — 파일을 작성함으로써 옵트인하는 방식은 정확히 무엇을 하는지 보여주고 명시적으로 선택하게 합니다.

작동 방식

게이트웨이 시작 시 HookRegistry.discover_and_load()가 ~/.hermes/hooks/를 스캔합니다.
HOOK.yaml + handler.py가 있는 각 하위 디렉토리가 동적으로 로드됩니다.
핸들러는 선언된 이벤트에 등록됩니다.
각 라이프사이클 지점에서 hooks.emit()이 일치하는 모든 핸들러를 실행합니다.
핸들러의 오류는 모두 캡처되어 로그에 기록됩니다. 잘못된 훅이 에이전트를 크래시시키지 않습니다.

:::info 게이트웨이 훅은 게이트웨이(Telegram, Discord, Slack, WhatsApp, Teams)에서만 실행됩니다. CLI는 게이트웨이 훅을 로드하지 않습니다. 모든 곳에서 작동하는 훅이 필요하면 플러그인 훅을 사용하세요. :::

요약

이제 간단한 텍스트 파일을 자동으로 실행되는 강력한 시작 체크리스트로 바꾸는 방법을 알게 되었습니다. 전체 에이전트 루프든 빠른 HTTP 호출이든 패턴은 동일합니다. 훅을 작성하고, 파일을 가리키고, 나머지는 Hermes가 처리하게 하면 됩니다.

다음 튜토리얼: 튜토리얼 27 — 음성 모드: 핸즈프리로 Hermes와 대화하기.