チュートリアル26: バッチ処理

これは Hermes Agent 公式チュートリアルシリーズの一部です。全チュートリアルを見る

これは、仕事を始める前に実行する朝のチェックリストのようなものだと思ってください。すべてのタスクを自分で覚えておく必要はなく、一度書き出しておけば、アシスタントが毎日自動的にチェックしてくれます。Hermes なら、ゲートウェイフックと BOOT.md というシンプルなファイルを使って、まさにそれを実現できます。

このチュートリアルでは、ゲートウェイが起動するたびに、カスタムの「バッチ」タスク（ログの確認、リマインダーの投稿、さらには考えて報告するミニエージェントの実行など）を Hermes に実行させる方法を学びます。

---

ステップ 1: フックディレクトリを作成する

まず、フックディレクトリ内にフォルダを作成します。各フックは、HOOK.yaml（設定）と handler.py（ロジック）の2つのファイルを持つ独自のサブフォルダに配置されます。

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()

重要な2行は次のとおりです。

• _resolve_gateway_model() は、ゲートウェイで現在設定されているモデルを読み取ります。
• _resolve_runtime_agent_kwargs() は、通常のゲートウェイターンと同じ方法でプロバイダーの認証情報（APIキー、ベース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 の初期バージョンでは、これを組み込みフックとして出荷し、ゲートウェイが起動するたびに、素のデフォルト設定でエージェントを静かに生成していました。これは、カスタムエンドポイントを使用しているユーザーを驚かせ、また、この機能が実行されていることを知らないユーザーには見えないものでした。これを文書化されたパターン（ユーザー自身がフックディレクトリ内に構築するもの）として維持することは、何が行われるかを正確に把握でき、ファイルを作成することでオプトインできることを意味します。

---

仕組み

1. ゲートウェイ起動時に、HookRegistry.discover_and_load() が ~/.hermes/hooks/ をスキャンします。
2. HOOK.yaml と handler.py を含む各サブディレクトリが動的にロードされます。
3. ハンドラーは、宣言されたイベントに対して登録されます。
4. 各ライフサイクルポイントで、hooks.emit() が一致するすべてのハンドラーを実行します。
5. ハンドラー内のエラーは捕捉されて記録されます。壊れたフックがエージェントをクラッシュさせることはありません。

:::info ゲートウェイフックは、ゲートウェイ（Telegram、Discord、Slack、WhatsApp、Teams）内でのみ実行されます。CLI はゲートウェイフックをロードしません。どこでも動作するフックについては、プラグインフック を使用してください。 :::

---

まとめ

これで、シンプルなテキストファイルを、自動的に実行される強力な起動時チェックリストに変える方法がわかりました。完全なエージェントループでも、簡単なHTTP呼び出しでも、パターンは同じです。フックを作成し、ファイルに向け、残りは Hermes に任せるだけです。

次回: チュートリアル 27 — ボイスモード: ハンズフリーで Hermes と話す。