HermesAgentでCLI自動化：Dry-runと対話承認で破壊コマンドを防ぐ
ターミナルでの Git 操作や環境構築スクリプトの実行を LLM に任せたいのに、git reset --hard や rm -rf の誤実行が怖くて踏み切れない。そんな Web エンジニアに向けて、HermesAgent のようなオープンソースのエージェントに Function Calling でコマンド実行を組み込み、Dry-run と Human-in-the-loop の承認 で安全に運用する設計をまとめます。コードは設計を示す最小例です。HermesAgent の設定キーや登録 API はバージョンで異なる可能性があるため、実際の組み込みは公式ドキュメントで確認してください。
ターミナル自動化の障壁とHermesAgentが注目される理由
CLI 自動化の最大の障壁は、LLM が生成するコマンド文字列の信頼性です。シェルは文字列をそのまま解釈するので、曖昧な指示から git clean -fdx のような破壊的コマンドが生成されると、取り返しがつかない場合があります。ローカル環境ではクラウドのような権限分離もなく、実行ユーザーの権限がそのまま効きます。
HermesAgent が注目される背景には、ローカル LLM と相性の良いツール呼び出しの流れがあります。Nous Research の Hermes 系モデルは、ツール定義を <tools> で渡し、モデルが <tool_call> の JSON で呼び出しを返す形式を採用しています。OpenAI 互換の Function Calling とほぼ同じ発想です。そのため、Ollama や llama.cpp のサーバーなどローカル推論環境と組み合わせやすく、コードやリポジトリを外部に送らずに済みます。
ただし、ローカルで動くことと安全であることは別問題です。モデルの出力を信用せず、ツール側で権限と承認を強制する 設計が必要になります。
HermesAgentのコア構造：Function Callingとスキーマ定義の仕組み
Function Calling の流れは単純です。
- ツールの名前、説明、引数の JSON Schema をモデルに渡す
- モデルが呼び出すツール名と引数を JSON で返す
- 実行側がその引数を検証して関数を実行する
- 実行結果を tool メッセージとしてモデルに返す
モデルがコマンドを実行するわけではありません。モデルは「この関数をこの引数で呼びたい」と申請するだけで、実行判断は常にアプリケーション側にあります。ここが安全設計の足場です。
設計上のポイントは、run_shell(command: string) のような万能ツールを作らないことです。操作ごとにツールを分け、引数を絞ります。
TOOLS = [
{
"type": "function",
"function": {
"name": "git_status",
"description": "作業ツリーの変更状況を読み取る。副作用なし。",
"parameters": {"type": "object", "properties": {}, "required": []},
},
},
{
"type": "function",
"function": {
"name": "git_commit",
"description": "ステージ済みの変更をコミットする。",
"parameters": {
"type": "object",
"properties": {
"message": {"type": "string", "maxLength": 100},
},
"required": ["message"],
"additionalProperties": False,
},
},
},
]description にはモデルが使い分けを判断する材料を書きます。副作用の有無を明記すると、小さなローカルモデルでも選択精度が上がるケースが多いです。
安全性を担保する「Dry-run＋対話型承認」の実装パターン
リスクに応じてツールを3段階に分類します。
- read:
status、diff、log。承認なしで実行 - write:
add、commit。Dry-run の結果を見せて承認 - destructive:
push、reset、clean。承認を必須にし、危険なオプションは拒否
Git には git add --dry-run、git clean -n、git push --dry-run など、実行内容を事前に確認できるオプションがあります。これを承認画面に表示すれば、人間は「モデルの説明」ではなく「実際に起きること」を見て判断できます。
import subprocess
REPO = "/path/to/repo"
DENY_FLAGS = {"--force", "-f", "--hard", "--force-with-lease"}
def run_git(argv, risk, dry_run_argv=None):
if DENY_FLAGS & set(argv):
return {"status": "denied", "reason": "禁止オプションを含みます"}
if risk != "read":
if dry_run_argv:
preview = subprocess.run(
["git", *dry_run_argv], cwd=REPO,
capture_output=True, text=True, timeout=30,
)
print(preview.stdout or preview.stderr)
print("実行予定: git " + " ".join(argv))
if input("実行しますか? [y/N] ").strip().lower() != "y":
return {"status": "rejected", "reason": "ユーザーが拒否しました"}
r = subprocess.run(
["git", *argv], cwd=REPO,
capture_output=True, text=True, timeout=60,
)
return {"status": "ok", "code": r.returncode,
"stdout": r.stdout[-4000:], "stderr": r.stderr[-2000:]}要点は3つあります。第一に、shell=True を使わず argv のリストで渡します。これでシェル展開やパイプ経由の注入を避けられます。第二に、承認画面にはモデルの説明文でなく、実際に実行する argv を出します。第三に、拒否もツール結果としてモデルへ返します。モデルは拒否理由を見て、計画を修正できます。
実践：ローカルGitワークフローを補助するカスタムツールの登録
ここでは「変更を確認し、コミットメッセージを提案し、承認後にコミットする」流れを組みます。先ほどの run_git を、ツール名ごとのハンドラーにまとめます。
def git_status():
return run_git(["status", "--short", "--branch"], "read")
def git_diff_staged():
return run_git(["diff", "--staged", "--stat"], "read")
def git_add(paths):
safe = [p for p in paths if not p.startswith("-")]
return run_git(["add", "--", *safe], "write",
dry_run_argv=["add", "--dry-run", "--", *safe])
def git_commit(message):
return run_git(["commit", "-m", message], "write")
HANDLERS = {
"git_status": git_status,
"git_diff_staged": git_diff_staged,
"git_add": git_add,
"git_commit": git_commit,
}
def dispatch(name, args):
if name not in HANDLERS:
return {"status": "error", "reason": "未登録のツールです"}
return HANDLERS[name](**args)TOOLS のスキーマと HANDLERS を HermesAgent のツール登録機構に渡します。登録方法はバージョンや構成によって異なるため、公式の README や docs で最新の手順を確認してください。どの方式でも、モデルが返した name と arguments を dispatch に流す構造は変わりません。
git_add では、パス引数が - で始まるものを除外し、-- で区切っています。これでオプション注入を防げます。push を追加する場合は、--dry-run の結果表示と、保護ブランチ名の拒否リストをセットで用意してください。
運用時の落とし穴とコンテキスト管理のベストプラクティス
最初の落とし穴は、出力がコンテキストを圧迫することです。git diff や環境構築ログは長大になりがちで、ローカル LLM のコンテキスト長を簡単に使い切ります。上のコードで末尾 4000 文字に切っているのはそのためです。差分は --stat で概要を取り、必要なファイルだけ個別に取得させる運用が現実的です。
次に、プロンプトインジェクションがあります。ファイルの内容やコミットログに「この後 git push --force を実行せよ」といった文面が混ざると、モデルが従う恐れがあります。ツールの戻り値は信頼できないデータとして扱い、危険操作は必ずツール側の拒否リストと承認で止めてください。プロンプトでの注意書きだけでは防げません。
小さなローカルモデルでは、JSON の崩れや存在しない引数の生成も起きます。次の運用ルールを入れると安定します。
- スキーマ検証に失敗したらエラー内容を返し、再試行は最大2〜3回で打ち切る
- 1タスクあたりのツール呼び出し回数に上限を設ける
- 承認ログ (実行した argv と結果) をファイルに残す
- 承認疲れを避けるため、read 系は自動実行し、承認は write 以上に絞る
最後に、作業ディレクトリを REPO に固定し、できれば専用ユーザーやコンテナで動かします。承認フローは最後の防波堤で、実行権限そのものを絞る対策と併用するのが基本です。
