DEV Community

Cover image for Apidog CLIのHermes Agentでの使い方
Akira
Akira

Posted on • Originally published at apidog.com

Apidog CLIのHermes Agentでの使い方

Hermes Agentはターミナルから実行され、セッション間で学習内容を記憶し、実際のシェルコマンドで作業を完了します。つまり、Hermesがコマンドを実行できるなら、APIテストも同じループで実行できます。

今すぐApidogを試す

この連携に使うランナーが、npmパッケージ apidog-cli として提供されるApidog CLIです。Apidogで作成したテストシナリオをターミナルから実行し、Hermesが判定に使える終了コードを返します。

この記事では、HermesでApidog CLIを使うために必要な実装手順に絞って説明します。

  • Hermesの terminal ツールで apidog run を実行する
  • AGENTS.md にAPIテストの実行ルールを書く
  • 終了コードを使ってHermesの修正ループに組み込む
  • 必要に応じてApidog MCPサーバーを接続し、API仕様をHermesに読ませる

CLIが未インストールの場合は、先にAIコーディングエージェントを使用したApidog CLIのインストール方法を完了してください。apidog --version がバージョン番号を返し、Apidogアカウントに少なくとも1つの保存済みテストシナリオがある状態から始めます。

「HermesでCLIを使用する」とは

Hermes Agentは、ターミナル上でAIモデルと対話し、組み込みツールを使って作業します。ここで重要なのが terminal ツールです。

Hermesは作業ディレクトリで terminal ツールを呼び出し、シェルコマンドを実行し、その出力を読み取って次の判断に使います。Apidog専用のHermesプラグインは不要です。

HermesでApidog CLIを使う作業は、次の3つです。

  1. Hermesにワークフローを教える

    AGENTS.md などのコンテキストファイルに、実行コマンド、フラグ、終了コードの扱いを書きます。

  2. Hermesに apidog run を実行させる

    通常のシェルコマンドと同じように、terminal ツール経由でAPIテストを実行します。

  3. 必要に応じてApidog MCPサーバーを接続する

    Hermesがコードを書くときに、Apidog上のAPI仕様を参照できるようにします。

ポイントは、チャットで毎回「このコマンドを実行して」と説明するのではなく、リポジトリに手順を固定することです。これにより、Hermesは同じルールを継続的に利用できます。

メカニズム: チャットのリマインダーではなくコンテキストファイル

Hermesはセッション開始時にプロジェクトコンテキストを読み込みます。作業ディレクトリ内の CLAUDE.md や AGENTS.md などの指示ファイルをスキャンし、システムプロンプトに注入します。

そのため、APIテストの実行方法はチャットではなく AGENTS.md に書くのが実用的です。

チャットに貼ったシナリオIDや環境IDは、そのセッションが終わると失われます。一方、AGENTS.md に書いた内容は、今後のHermes実行やチームメイトの作業でも再利用できます。

Hermesは SOUL.md も読み取りますが、これはエージェントのペルソナ向けです。プロジェクト固有のAPIテスト手順は AGENTS.md に置いてください。

ステップ1: AGENTS.md にApidogブロックを追加する

リポジトリルートに AGENTS.md を作成、または既存ファイルを開きます。そこに、Hermesが使うApidog CLIの実行ルールを追加します。

重要なのは、抽象的な説明ではなく、実際に実行すべきコマンドとIDを書くことです。

## Apidog CLIによるAPIテスト

このリポジトリは、Apidog CLI（`apidog-cli`、`apidog`コマンド）を使用してAPI
テストシナリオを実行します。シナリオは、このリポジトリではなく、Apidogプロジェクトに存在します。

APIハンドラ、ルート、またはレスポンスの形状を変更した場合、変更が完了したと
見なす前に、関連するApidogシナリオをterminalツールを通じて実行してください：

    apidog run -t 605067 -e 1629989 -n 1 -r cli

- `-t 605067` はチェックアウトフローのテストシナリオです。
- `-e 1629989` はステージング環境です。
- マシンは`apidog login`によって既に認証されているため、
  アクセストークンを渡したり、出力したりしないでください。

終了コードを信頼できる情報源として扱います：`0`はすべてのアサーションが成功したことを意味し、
非ゼロは失敗を意味します。非ゼロで終了した場合は、レポート内の失敗したアサーションを読み、
コードを修正してから再実行してください。非ゼロ終了の場合に成功を報告しないでください。
Enter fullscreen mode Exit fullscreen mode

605067 は実際のシナリオIDに、1629989 はHermesがアクセスしてよい環境IDに置き換えてください。通常はステージング環境またはローカル開発環境を使います。本番環境をHermesの自動実行対象にするのは避けてください。

このブロックには2つの役割があります。

  • HermesがフラグやIDを推測しないようにする
  • 終了コードをテスト結果の信頼できる情報源として扱わせる

これにより、テストが失敗しているのにHermesが「成功しました」と要約してしまう問題を防ぎやすくなります。

ステップ2: Apidogから正しいコマンドを取得する

Hermesに実行させる前に、Apidogで生成された正しいコマンドを確認します。

  1. Apidogで対象シナリオを開く
  2. CI/CDタブに移動する
  3. コマンドラインオプションを選択する
  4. 生成された apidog run コマンドをコピーする

例:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

ここで:

  • 605067 はシナリオID
  • 1629989 は環境ID
  • --access-token はCIや未ログイン環境向けの認証情報

ローカルマシンで apidog login 済みの場合、--access-token YOUR_ACCESS_TOKEN は削除します。トークンを AGENTS.md にコミットしないでください。

Hermesに書かせる、または実行させるコマンドは次の形にします。

apidog run -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

ステップ3: Hermesにテストを実行させる

リポジトリルートでHermesを起動し、AGENTS.md のルールに従ってAPIテストを実行させます。

プロンプト例:

AGENTS.mdに記述されている通りに、Apidog APIテストシナリオを実行してください。私はすでに認証済みなので、アクセストークンは渡さないでください。apidog run -t 605067 -e 1629989 -n 1 -r cliを使用してください。完全な出力と終了コードを教えてください。

Hermesは terminal ツールを使って、作業ディレクトリでコマンドを実行します。-r cli レポーターを指定すると、ステップごとの実行結果がターミナルに出力されるため、Hermesは各リクエストやアサーション結果を読み取れます。

設定によっては、Hermesがコマンド実行前に承認を求めることがあります。ステージング環境に対する読み取り中心のテストであれば、通常は安全なワークスペース内コマンドとして許可できます。

確認すべきなのは、Hermesの文章ではなく終了コードです。

  • 0: すべてのアサーションが成功
  • 非ゼロ: 少なくとも1つの失敗あり

Hermesが「テストはパスしました」と言っても、終了コードが非ゼロなら失敗です。終了コードを優先してください。

利用可能なフラグやレポーターを確認したい場合は、Hermesに次を実行させます。

apidog run --help
Enter fullscreen mode Exit fullscreen mode

詳細なフラグはApidog CLI完全ガイドにも記載されています。html、json、junit などのレポーターを利用できます。

ステップ4: Hermesの編集・テスト・修正ループに組み込む

AGENTS.md にルールを書いておくと、Hermesはあなたが毎回指示しなくても、API関連の変更後にテストを実行しやすくなります。

たとえば、チェックアウトレスポンスを返すハンドラをHermesが編集する場合、理想的なループは次のようになります。

  1. HermesがAPIハンドラを編集する
  2. terminal ツールでApidogシナリオを実行する
  3. apidog run の終了コードを読む
  4. 成功なら作業を完了する
  5. 失敗ならレポート内の失敗アサーションを読む
  6. ステータスコード、欠落フィールド、誤った値などを修正する
  7. 再度 apidog run を実行する

これにより、ApidogのAPIテストをユニットテストと同じように編集・テスト・修正ループへ組み込めます。

実行時間が長いシナリオや大きなテストセットを扱う場合、Hermesの terminal ツールは background=true フラグを受け取れます。これにより、Hermesはテストをバックグラウンドで開始し、他の作業を続けながら終了コードをポーリングできます。

AIエージェントとAPIテストのより広いパターンは、APIテストにAIエージェントを使用する方法およびApidog AIテストハーネスを参照してください。

オプション: Apidog MCPサーバーを接続する

Apidog CLIは、Hermesにテストを実行させます。一方、Apidog MCPサーバーは、Hermesがコードを書いている間にAPI仕様を読み取るために使います。

この2つは補完関係です。

  • MCP: HermesにスキーマやAPI仕様を渡す
  • CLI: 実装が実際のシナリオに合っているか検証する

HermesはModel Context Protocolをサポートしています。Apidog MCPサーバーを接続するには、~/.hermes/config.yaml に mcp_servers エントリを追加します。

mcp_servers:
  apidog:
    command: "npx"
    args: ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"]
    env:
      APIDOG_ACCESS_TOKEN: "YOUR_ACCESS_TOKEN"
Enter fullscreen mode Exit fullscreen mode

保存後、Hermes内で次を実行します。

/reload-mcp
Enter fullscreen mode Exit fullscreen mode

またはHermesを再起動します。

Hermesは起動時にMCPサーバーを検出し、ツールを mcp_apidog_<tool> のように名前空間付きで登録します。これにより、Hermesは通常の推論中にApidog上のAPI仕様を参照できます。

プロジェクトIDやトークンを含む詳細な設定は、Apidog MCPサーバーガイドを参照してください。このループを別の形でパッケージ化した例は、Claude SkillsとApidog CLIガイドにあります。

ローカルループからCIへ

Hermesがローカルでシナリオを実行し、終了コードに基づいて判断できるようになったら、CIでも同じコマンドを使えます。

違いは認証方法です。

  • ローカル: apidog login 済みの認証情報を使用
  • CI: マスクされたシークレットからアクセストークンを渡す

HermesにGitHub Actionsステップを書かせる場合のプロンプト例:

apidog-cliをインストールし、リポジトリシークレットAPIDOG_ACCESS_TOKENからアクセストークンを読み取ってapidog run -t 605067 -e 1629989 -r junitを実行するGitHub Actionsステップを記述してください。

GitHub Actionsでのシークレット、レポーター、終了コードゲートの扱いは、GitHub ActionsでのApidog CLIにまとまっています。

同じ apidog run コマンドを、次の3か所で使い回せます。

  • 開発者のターミナル
  • Hermesのローカル修正ループ
  • CIパイプライン

判定基準はいずれも終了コードです。

よくある落とし穴

Hermesがコンテキストブロックを無視する

AGENTS.md または CLAUDE.md が、Hermesを起動した作業ディレクトリに存在するか確認してください。ファイル名のスペルも確認します。

修正後はHermesセッションを再起動すると、コンテキストが再読み込みされます。

コマンドを実行せず、提案だけする

Hermesは承認レイヤーを介して terminal ツールでコマンドを実行します。実行承認待ちになっていないか確認してください。

設定でターミナルコマンドが拒否されている場合は、apidog run の実行を許可します。

apidog whoami が未認証と表示される

ログイン情報はHermesではなく、ローカルマシン側に保存されます。

自分で次を実行してログインしてください。

apidog login --with-token
Enter fullscreen mode Exit fullscreen mode

その後、Hermesに確認させます。

apidog whoami
Enter fullscreen mode Exit fullscreen mode

トークンをチャットやログに出力しないでください。

Hermesが存在しないフラグを使う

unknown option のようなエラーが出た場合、Hermesが現在のCLIバージョンに存在しないフラグを推測している可能性があります。

次を実行させ、実際のフラグを確認します。

apidog run --help
Enter fullscreen mode Exit fullscreen mode

確認したフラグを AGENTS.md に反映してください。

失敗した実行を成功として報告する

最も避けるべき問題です。AGENTS.md に終了コードのルールを書き、手動でも確認してください。

  • サマリーが成功
  • 終了コードが非ゼロ

この場合は失敗です。終了コードを信頼してください。

まとめ

HermesでApidog CLIを使うために必要なのは、主に次の2つです。

  1. AGENTS.md にApidog CLIの実行コマンド、認証方針、終了コードルールを書く
  2. Hermesに terminal ツール経由で apidog run を実行させ、終了コードを確認する

必要に応じて ~/.hermes/config.yaml にApidog MCPサーバーを追加すれば、Hermesはコード作成中にAPI仕様も参照できます。

シナリオの作成と管理はApidogで行い、Hermesにはそれを実行させます。次のステップとして、GitHub ActionsのApidog CLIでCIに組み込むか、完全ガイドでフラグ一覧を確認してください。

よくある質問

Apidog CLIを使用するためにHermesプラグインは必要ですか？

いいえ。Hermesは terminal ツールを介してシェルコマンドを実行するため、apidog run を直接呼び出せます。Hermes固有の設定は、AGENTS.md ブロックと、必要に応じたMCPサーバー設定だけです。

Hermesにワークフローを教える指示はどこに置けばよいですか？

Hermesが起動時に読み込むコンテキストファイルに置きます。通常はリポジトリルートの AGENTS.md にApidogブロックを追加します。Hermesは AGENTS.md や CLAUDE.md のようなファイルをスキャンし、システムプロンプトに注入します。

Hermesがテスト成功を偽装しないようにするにはどうすればよいですか？

サマリーだけでなく、終了コードを必ず報告させてください。apidog run は、すべてのアサーションが成功した場合にのみ 0 で終了します。テキストの説明と終了コードが矛盾する場合は、終了コードを信頼します。

Apidog MCPサーバーをHermesに接続するにはどうすればよいですか？

~/.hermes/config.yaml に apidog-mcp-server コマンドとプロジェクトIDを含む mcp_servers エントリを追加します。その後、Hermes内で /reload-mcp を実行するか、Hermesを再起動してください。詳細はApidog MCPサーバーガイドを参照してください。

これは他のAIコーディングエージェントでも同じように機能しますか？

CLIの実行方法は同じです。ただし、エージェントにワークフローを教える方法は異なります。Hermesは AGENTS.md を読み込み、terminal ツール経由でコマンドを実行します。他のエージェントでは、それぞれの指示ファイルや設定に合わせて同じ apidog run コマンドを登録してください。インストールと認証の流れは、インストールガイドを参照できます。

Top comments (0)