これは、APIテストおよびAPIライフサイクル管理のためのコマンドラインツールであるApidog CLIがどのように開発されたかを共有する10部構成のシリーズです。順番に読むか、興味のある記事に直接進んでください。
| タイトル | 焦点 | |
|---|---|---|
| 1 | 私たちは126のMCPツールを構築しました。しかし、それはAgentにとって最善の解決策ではありません。 | 問題の発見 |
| 2 | なぜ私たちは全く新しいApidog CLIを開発したのか | アーキテクチャ開発 |
| 3 | 黄金律：CLIはファクトを生成し、モデルはファクトに基づいて行動する | コア哲学 |
| 4 | agentHints：CLIにAgentとの対話方法を教える |
構造化された出力 |
| 5 | SKILL：運用経験をコードとして出荷する | 運用経験 |
| 6 | 数字は嘘をつかない：ツール呼び出し30%減、トークン25%減 | 定量的な結果 |
| 7 | PRDからテストループまで：Apidog CLIを使用した完全なAgentワークフロー | 実践チュートリアル |
| 8 | AgentツールにとってCI/CD互換性が不可欠である理由 | DevOpsの視点 |
| 9 | AIブランチ：AI Agentによるより安全なプロジェクト変更 | セキュリティレイヤー |
| 10 | Spec-Firstは昨日。Skill-Firstへようこそ。 | ビジョンと未来 |
従来のCLI出力は人間向けです。Agentには、構造化された結果、失敗理由、次ステップの提案が必要です。agentHintsは、製品経験を機械可読なガイダンスとしてCLI出力に埋め込みます。
CLI出力のギャップ
従来のCLI出力は、基本的に人間が読むことを前提に設計されています。
| 成功時 | 失敗時 |
|---|---|
| 「成功」または「完了」と表示する | エラーメッセージを表示する |
| 作成されたリソースを表示する場合がある | スタックトレースを表示する場合がある |
| 人間が読んで次の操作を判断する | 人間が読んでデバッグする |
人間であれば、次のような判断ができます。
- 曖昧なメッセージを文脈から解釈する
- 次に実行すべきコマンドを選ぶ
- 直前の操作や目的を記憶している
- ドメイン知識を使って回復手順を考える
しかし、Agentは同じようには動きません。Agentに必要なのは「読める文章」ではなく、次のアクションに接続できる構造化された事実です。
AgentがCLI出力に求めるもの
Agentはコマンド結果を受け取ったあと、その結果を次のタスクに接続する必要があります。
| Agentが必要とする情報 | 理由 |
|---|---|
| 構造化された結果 | 出力をプログラム的にパースするため |
| 失敗の理由 | 一般的なエラーではなく、修正対象を特定するため |
| 次ステップの提案 | 次に実行すべき操作を判断するため |
たとえば、人間は「リソースが正常に作成されました」と表示されれば、次のように考えられます。
- 作成されたリソースを確認する
- 必要ならフィールドを修正する
- テストケースやシナリオに追加する
- 実行して結果を見る
一方、Agentが同じメッセージだけを受け取ると、「作成が成功した」という事実は分かっても、次に何をすべきかは明示されていません。
agentHints：CLI出力に次ステップを含める
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つです。
| フィールド | 役割 |
|---|---|
success + data
|
実際の実行結果 |
agentHints.summary |
人間にも読みやすい要約 |
agentHints.nextSteps |
Agentが次に選べるアクション候補 |
Agent側では、たとえば次のように処理できます。
const result = await runCliCommand();
if (result.success) {
const nextStep = result.agentHints?.nextSteps?.[0];
if (nextStep) {
console.log("Recommended next step:", nextStep);
}
} else {
console.error(result.error);
console.log(result.agentHints?.summary);
}
重要なのは、CLIが単に成功・失敗を返すだけでなく、ワークフロー上の次の安全な操作も返すことです。
実行慣性の問題
Agentワークフローでよく起きる問題が、実行慣性です。
リソースの作成に成功すると、モデルはそのまま次の書き込み操作を続けがちです。
Agent: テストケースを作成
CLI: 成功を返す
Agent: 読み戻しなしでテストシナリオを作成
Agent: すぐにテストを実行
結果: シナリオ構造が実データと合わず、テストが失敗
複雑なAPIテストや業務フローでは、機械的に次の書き込みへ進むのは安全ではありません。
より安全な流れは次のとおりです。
- リソースを作成する
- 作成されたリソースを読み戻す
- 実際の構造を確認する
- その構造に基づいて次の操作を行う
agentHintsは、この「読み戻し」をAgentに明示的に促すために使えます。
読み戻しが重要な理由
読み戻しをスキップすると、Agentは実データではなく推測に基づいて次の操作を行います。
| 問題 | 原因 |
|---|---|
| 誤ったデフォルト値 | サーバーがAgentの指定していない値を補完する |
| 関連IDの欠落 | インポートや作成処理で新しい内部IDが生成される |
| 構造の差異 | フロントエンドやAPIが特定のパース結果に依存する |
| 誤った仮定 | Agentが「おそらくこうなっている」という想像で続行する |
そのため、作成・更新のあとには次のようなループが必要です。
write → read back → inspect → continue
agentHintsは、このループをCLI出力の中で明示します。
ナビゲーターとしての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はこの出力を使って、次のように進められます。
- CLI出力を受け取る
-
agentHints.nextStepsをパースする -
nextSteps[0]に従ってテストケースを読み戻す - 実際の構造を確認する
- 確認済みの情報を使って次の操作を行う
つまり、CLIは単なる実行結果ではなく、その時点で安全に進むためのナビゲーション情報を返します。
CLIの役割は「実行者」から「ナビゲーター」へ変わる
Agentワークフローでは、CLIの役割も変わります。
| 古いCLIの役割 | Agent時代のCLIの役割 |
|---|---|
| コマンドを実行する | ワークフローを案内する |
| 結果を表示する | 次の操作を提案する |
| 人間が読む出力を返す | Agentがパースできる構造を返す |
| 単発の応答を返す | 継続的なガイダンスを返す |
この設計により、CLIは軽量なステータスナビゲーターになります。
Agentは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を使うと、Agentの操作は次のようなループになります。
ステップ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ありとなし
| シナリオ |
agentHintsなし |
agentHintsあり |
|---|---|---|
| 作成後 | Agentは次の書き込みへ進みがち | Agentはまず読み戻す |
| 更新後 | Agentは成功したと仮定する | Agentは構造を確認する |
| バリデーション通過後 | Agentはすぐに書き込む | Agentは書き込み後に読み戻す |
| バリデーション失敗後 | Agentはエラー処理に迷う | Agentは具体的な修正候補を得る |
| テスト実行後 | Agentは合否だけを見る | Agentはデバッグ手順を得る |
実装の観点では、CLI出力に以下を含めるだけでAgentの振る舞いを改善できます。
{
"success": true,
"data": {},
"agentHints": {
"summary": "Operation completed.",
"nextSteps": [
"Read back the resource before making further changes.",
"Validate the updated structure before writing.",
"Run related tests after changes are complete."
]
}
}
ポイントは、nextStepsを単なる説明文ではなく、Agentが実行順序を判断するための構造化された配列として返すことです。
次は何ですか
CLIがAgentに次のステップを案内できるようになると、次の疑問が出てきます。
Agentは、そもそもどのワークフローに従うべきかをどうやって知るのでしょうか？
第5部、SKILL：運用経験をコードとして出荷するでは、SKILLがワークフロー知識をどのようにパッケージ化するかを扱います。
具体的には、次のような知識です。
- どのタイミングでどのコマンドを使うか
- どの順序で操作を進めるか
- どのフィールドを推測してはいけないか
- どこで読み戻しや検証を挟むべきか
主要なポイント
- 従来のCLI出力は人間向けであり、Agentには構造化されたガイダンスが必要
-
agentHintsはJSON出力に要約と次ステップの提案を追加する - Agentは成功後に次の書き込みへ進みがちなので、読み戻しを明示する必要がある
- CLIは単なる実行者ではなく、Agentワークフローのナビゲーターになれる
- 成功時だけでなく、失敗時にも修正手順を提示できる
-
agentHintsにより、作成・読み戻し・検証・実行のループを安全に進められる
Apidogをダウンロードして、1つのワークスペースでAPIの設計、モック、テスト、ドキュメント作成を行いましょう。コマンドラインAPIテスト、CI自動化、AI Agentワークフローに関するApidog CLIの詳細については、こちらをご覧ください。
Top comments (0)