agentHints: CLIsとエージェントの対話を実現する

これは、APIテストおよびAPIライフサイクル管理のためのコマンドラインツールであるApidog CLIがどのように開発されたかを共有する10部構成のシリーズです。順番に読むか、興味のある記事に直接飛んでください：

従来のCLI出力は人間向けです。Agentは構造化された結果、失敗の理由、次ステップの提案を必要とします。agentHintsは、製品経験を機械可読なガイダンスに変換します。

CLI出力のギャップ

従来のCLI出力は**人間**向けに設計されています。

これは人間には機能します。人間は：

• 曖昧なメッセージを解釈する
• 次に何をすべきかを決定する
• 以前のコマンドのコンテキストを記憶する
• 専門知識を適用して続行する

しかし、Agentの動作は異なります。

Agentが本当に必要とするもの

Agentは単に結果を読むだけではありません。**結果を次のタスクチェーンに接続する**必要があります。

人間は「リソースが正常に作成されました」と見て、「おそらく作成されたものを確認し、その後いくつかのテストを実行すべきだ」と理解します。

Agentは「リソースが正常に作成されました」と見て…次に何をすべきか全く分かりません。

agentHints：ソリューション

Apidog CLIは、その出力にagentHintsを追加します。

典型的な応答は次のようになります：

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Test case created successfully.",
    "nextSteps": [
      "Read the created test case back to confirm structure.",
      "Add assertions if the test case needs response validation.",
      "Add the test case to a test scenario for integration testing.",
      "Run related tests after adding to scenario."
    ]
  }
}

3つのコンポーネント：

実行慣性の問題

私たちが観察した実際の問題は次のとおりです：

リソースを正常に作成した後、モデルはしばしば次の書き込みを直接生成し続けます。

例：

Agent: テストケースを作成
CLI: 成功を返す
Agent: (読み戻しなしに)すぐにテストシナリオを作成
Agent: すぐにテストを実行
結果: シナリオの構造が間違っており、テストが失敗

複雑なビジネスプロセスにおいて、**機械的な継続実行は適切ではありません。**

最も正しいアプローチはしばしば次のとおりです：

1. リソースを作成
2. **まず読み戻す**
3. 構造を確認
4. それから続行

読み戻しが重要な理由

読み戻しをスキップすると、実際の問題が発生します：

実際の構造が読み戻されない場合、Agentは自身の推測に基づいて書き込みを続けがちであり、実際のデータに基づきません。

ナビゲーターとしてのagentHints

agentHintsは、製品経験を機械可読な次ステップの提案に変換します。

それは、**Agentが意思決定をする必要があるまさにその場所**に表示されます。

テストケース作成後の例：

{
  "agentHints": {
    "nextSteps": [
      "Read back the created test case with --with-case-detail flag.",
      "Validate any updates with cli-schema before writing.",
      "Run tests after completing test scenario."
    ]
  }
}

Agentは：

1. 出力を読む
2. agentHintsをパースする
3. nextSteps[0]に従う：テストケースを読み戻す
4. 実際の構造を確認する
5. その後、正確な情報に基づいて続行する

CLIの役割変換

これにより、AgentワークフローにおけるCLIの意味が変化します。

CLIは軽量なステータスナビゲーターになります。

組み込みのワークフローツリー

Apidog CLIには、組み込みの**何千ものツリー構造ワークフロー**があります。

これらは単なるハードコードされた提案ではありません。それらは：

テストシナリオの更新成功後の例：

{
  "agentHints": {
    "summary": "Test scenario updated successfully.",
    "nextSteps": [
      "Run the test scenario to verify changes.",
      "Check the test report for any failures.",
      "If failures occur, read back scenario steps for debugging."
    ]
  }
}

バリデーション失敗後の例：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": [...]
  },
  "agentHints": {
    "summary": "Validation failed. Fix the errors and re-validate.",
    "nextSteps": [
      "Review the error details in the output.",
      "Adjust the JSON file based on error suggestions.",
      "Re-run cli-schema validate before writing."
    ]
  }
}

失敗でさえもナビゲート可能になります。

agentHintsによるより安全なループ

agentHintsを使用した完全なワークフローを追ってみましょう：

ステップ1: Agentがテストケースを作成
        ↓
CLI出力: success + agentHints
        ↓
agentHints.nextSteps[0]: 「作成されたテストケースを読み戻す」
        ↓
ステップ2: Agentが読み戻す (実際の構造で)
        ↓
CLI出力: テストケース構造 + agentHints
        ↓
agentHints.nextSteps[0]: 「必要に応じてアサーションを追加」
        ↓
ステップ3: Agentがアサーションを追加する (実際の構造に基づいて)
        ↓
CLI出力: success + agentHints
        ↓
agentHints.nextSteps[0]: 「テストを実行」
        ↓
ステップ4: Agentがテストを実行
        ↓
CLI出力: テストレポート

すべてのステップがガイドされます。盲目的なジャンプはありません。仮定もありません。

比較：agentHintsありとなし

次は何ですか

CLIがAgentに次のステップをガイドできるようになった今、残る疑問は次のとおりです：

Agentはそもそもどのワークフローに従うべきかをどうやって知るのでしょうか？

第5部、SKILL：運用経験をコードとして出荷するでは、SKILLがどのようにワークフロー知識（いつコマンドを使用するか、どの順序に従うか、どのフィールドを推測すべきでないか）をパッケージ化するかを探ります。

主要なポイント

• 従来のCLI出力は人間指向であり、Agentは構造化されたガイダンスを必要とする
• agentHintsはJSON出力で要約と次ステップの提案を提供する
• 実行慣性によりAgentは読み戻しをスキップするが、agentHintsはこれを防ぐ
• CLIは実行者からナビゲーターへと役割を変換する
• 組み込みのワークフローツリーにより、すべてのステップがナビゲート可能になる
• agentHintsがあれば、失敗でさえも対処可能になる

Apidogをダウンロードして、1つのワークスペースでAPIの設計、モック、テスト、ドキュメント作成を行いましょう。コマンドラインAPIテスト、CI自動化、AI Agentワークフローに関するApidog CLIの詳細については、こちらをご覧ください。