なぜ、あなたのAPIは使われないのか？ AX時代の設計原則、ガードレール、運用体制

Presentation Slides: AI DevEx Conference 2026 (session)
Session Title: なぜ、あなたのAPIは使われないのか？ AX時代の設計原則、ガードレール、運用体制 / Why isn't your API being used? Design principles, guardrails, and operational structures in the AX era
Date: 2026/07/22

Transcript

1. なぜ、あなたのAPIは使われないのか？ AX時代の設計原則、ガードレール、運用体制 AI DevEx Conference 2026 #aidevex_findy 川崎庸市 テクノロジーエバンジェリスト All rights reserved by Postman Inc
2. 川崎 庸市 / Yoichi Kawasaki テクノロジーエバンジェリスト Postman株式会社 @yokawasa @postman_japan
3. 話すこと • • • • AIエージェント時代のプロダクトの変化 AX（Agent Experience）とは？ AXを支える3本の柱 まとめ
4. AIエージェント時代のプロダクトの変化
5. AI以前からあった、ヘッドレス化のトレンド フロントエンドとバックエンドを分離し、UIをAPI経由でデータを取得する構成にする — この「ヘッドレス化」は、AI以前からのアーキテクチャの潮流だった Jamstack JavaScript, APIs Markup https://www.lifeintech.com/2017/12/20/jamstack/ MACH Microservices-based, API-first, Cloud-native SaaS, Headless What is MACH Architecture? https://www.sunriseintegration.com/learn/what-is-mach -architecture Composable How do composable, headless and MACH compare? The key differences explained https://commercetools.com/blog/how-do-composa ble-headless-and-mach-compare-the-key-differen ces-explained
6. SaaS is Dead ― プロダクトのヘッドレス化 • • AIエージェントの台頭により、UI（画面）は必須の入口ではなくなった プロダクトのヘッドレス化 = 従来の「人間がUI（画面）を操作」→「AIエージェントがAPIを介して直接シ ステム（データ）を操作」へのシフト 従来モデル AIエージェント時代 UI（画面） MCP・CLI API API データ データ
7. SaaS is Dead ― プロダクトの価値の中心の変化 • • SaaSが UI中心の業務アプリから、AIエージェントが業務を実行・調整するための基盤へ進化 価値の中心の変化： UI → 「データ、業務ロジック、ガバナンス、など」能力そのものへ 複数システムを束ねる エージェントがタスクを実行 人の仕事の流れを管理 業務データの保存 Is Software Losing Its Head? https://www.a16z.news/p/is-software-losing-its-head
8. AIエージェント時代の主要インターフェース • • • 人間向けのUIからエージェント向け実行インターフェースが重要になる 主役はMCP。その他 CLI、SDK、Webhook、APIなど用途別にエージェントが利用 各接点を支える実体・土台としてのAPI 接点 主な利用者 役割 UI 人間 人向けの入口。人が見て、判断・操作する API アプリ、AIエージェント、開発者 各接点の土台、機能の実体。人・ AI両方が利用 MCPサーバー AIエージェント（特化） エージェントが使う道具として発見・実行 CLI 開発者、運用者、AIエージェント 実行・管理を行う。人・ AI両方が利用 SDK 開発者、AIエージェント 主に開発者向け API利用補助。人・ AI両方が利用 Webhook システム、AIエージェント イベント通知の入口
9. AIエージェント時代のプロダクト構造 ４層で捉える: ( 1 ) 利用者層 / ( 2 ) 接点層 / ( 3 ) 骨格層API・サービス基盤) / ( 4 ) データ基盤層 利用者層 利用する人・システム・エージェントなどの利用者層 接点層 エージェントやユーザーなどの使い方に合わせて 機能・データへの アクセスを提供するための「入口」 MCP・CLI・SDK・Web UI・Webhookなど 骨格層 （API） API／サービス基盤（プロダクトの骨格） ビジネスロジック、権限管理、ワークフローなどプロダクトの中核を担う層 データ 基盤層 業務データを安全に保管し、整合性・可用性・ガバナンスを支える土台 業務データ、メタデータ、検索、監査、データガバナンス・コンプライアンスなど
10. AIエージェント時代のプロダクト構造 ４層で捉える: ( 1 ) 利用者層 / ( 2 ) 接点層 / ( 3 ) 骨格層API・サービス基盤) / ( 4 ) データ基盤層 利用者層 接点層 骨格層 （API） データ 基盤層 人間ユーザー チャット UI AIエージェント 開発者・システム連携 パートナー・外部開発者 ブラウザ・モバイル ChatGPT・Claude など 自律的にタスク実行 自社システム・iPaaS 外部との連携 Web UI MCPサーバー CLI モバイルアプリ （Tools・Resources・Prompts） 開発・運用の自動化 認証・認可 ビジネスロジック データアクセス ID・権限管理 業務ルール・計算 CRUD・検索 業務データ 顧客・注文・契約 メタデータ／ カタログ 検索インデックス SDK／ライブラリ ワークフロー／ オーケストレーション キャッシュ／ セッションストア バックアップ／ リカバリ Webhook 通知・リアルタイム連携 監査・ログ 可観測性 データガバナンス／ コンプライアンス
11. • プロダクトの接点の中心がUI MCP、CLI、API、etc.にシフト ◦ • プロダクトの骨格としてのAPI ◦ • ⇒ APIを含めUI以外の接点層を通じたプロダクトの能力提供が必要になる 接点が安全・正確・安定して価値を提供するには、プロダクト能力を一貫して提供する骨格層、 API層が重要にな る。機能、データ、権限、業務ルール、状態管理、など 人間ユーザー 利用者層 チャット UI AIエージェント 開発者・システム連携 ブラウザ・モバイル ChatGPT・Claude など 自律的にタスク実行 自社システム・iPaaS 接点の品質は、その奥の骨格層（API）・データ基盤層に強く依存 ◦ パートナー・外部開発者 外部との連携 価値の重心はUI奥の骨格層・データ基盤層に移動し、提供可能な能力の質を決める比重が増した 接点層 Web UI MCPサーバー CLI （Tools・Resources・Prompts） 開発・運用の自動化 価値の重心 骨格層 （API） SDK／ライブラリ Webhook 通知・リアルタイム連携 プロダクト能力の共通骨格 認証・認可 ビジネスロジック データアクセス ID・権限管理 業務ルール・計算 CRUD・検索 ワークフロー／ オーケストレーション 監査・ログ 可観測性 価値の重心 データ 基盤層 業務データ 顧客・注文・契約 メタデータ／ カタログ 検索インデックス キャッシュ／ セッションストア バックアップ／ リカバリ データガバナンス／ コンプライアンス
12. AX（Agent Experience）とは？
13. AXとは何か ― Agent Experience の定義 AX定義1 AX定義2 AIエージェントが迷わす製品 を理解し、自律的に確実に 操作できるように設計すること AIエージェントがAPIや関連する道 具を発見し、意味を理解し、 正しく実装・実行し、失敗時に 回復でき、人間がその動作を 確認・制御・改善できる体験設計 出典: Art Anthonyの記事, What Is Agent Experience AX? https://nordicapis.com/what-is-agent-experience-ax/ 出典: Kevin Whinnery、Stainless Head of Marketing & DevRelの記事 Steps toward great agent experience every API provider can take today https://www.stainless.com/blog/steps-toward-great-agent-experience -every-api-provider-can-take-today/
14. AXの議論で、よくある問い MCPかAPIかCLIか、どっちが良いか？
15. 参考情報 どういう時に、どの接点が向いているか 接点 主な利用者 向いている場面 UI 人間 人が視覚的に操作・確認する。学習コストが低い API アプリ、AIエージェント、開発者 あらゆる接点の土台。プログラムからの直接連携、最も柔軟。同期 的なリクエスト/レスポンスが基本 MCPサーバー AIエージェント（特化） エージェントにコンテキスト付きで能力を渡す。ツール発見・呼び出し を標準化したいとき（なお、認可など仕様はまだ成熟段階） CLI 開発者、運用者、AIエージェント スクリプトや自動化に組み込む。ターミナル起点の操作、CI/CDとの 親和性がよい SDK 開発者、AIエージェント 特定言語のアプリへの統合。型安全に素早く実装したい時 Webhook システム、AIエージェント 外部への通知、リアルタイム連携。イベント駆動・非同期（push型）。 エージェントを起動するトリガーにもなる
16. AXの本質 • • 問うべきは「何を選ぶか」ではなく「どんな価値 (能力)を提供できるか」 AXの本質とは、どの入口からも同じ品質の能力を返せるよう、接点だけでなく骨格 （API）と土台（データ基盤）まで含めて設計することである エージェントが安全に使うために必要なもの MCP・CLI 機械可読な仕様 監査ログ アクセス制御 安定したAPI エラー設計 ガバナンス 権限管理 テスト可能性 一貫性のあるデータ API データ
17. なぜあなたのAPIは使われなくなるのか？ ⇒ 答えはAX（Agent Experience）にある AIエージェントが迷わす製品を理解し、自律的に確実に操作できるようにするための体 験設計が十分ではないことが要因 エージェントが安全に使うために必要なもの MCP・CLI 機械可読な仕様 監査ログ ❌アクセス制御 安定したAPI エラー設計 ❌ガバナンス ❌権限管理 ❌テスト可能性 一貫性のあるデータ API データ
18. エージェント体験（＝AX）の設計を どう支えるのか？
19. AXを支える3本柱 設計原則 ガードレール 運用体制 迷わせない 秩序を与える 継続的に保つ
20. 柱1：設計原則 迷わせない
21. 柱1 設計原則 AIエージェントを迷わせない • • • これまで、人間は空気を読んで曖昧さや暗黙知を補完していた だがAIは補完しない。曖昧さは、そのまま迷いになる（誤動作・エラー） 必要なのは、AIを迷わせないための体験設計＝AX 人間 • • • 曖昧でも文脈で察する 詰まれば人に聞く 慣習や行間を補って使う 曖昧さ・暗黙知を人が補完 AIエージェント • • • 書かれた仕様の通りにしか動けない 暗黙の前提は機能しない 曖昧さは誤動作・エラーに 暗黙知が通用しない
22. 柱1 設計原則 なぜ迷うのか？ ReAct Reaction + Action) 多くのAIエージェントの行動モデルはReAct的 • • • • • ユーザーの目標やプロンプトを受け取る → 内部で思考プロセス Chain-of-Thought) を展開 → 必要に応じてツール API、MCP、CLIなど)を実行 → 観察（Observation） → 次のステップを決定 Start Thought Action Observation エージェントは、観察（Observation）で得た情報を頼 りに次の一手を決める。ツールが返す結果の質が悪け れば、観察も鈍り、判断を誤る ReAct: SYNERGIZING REASONING AND ACTING IN LANGUAGE MODELS (Yao et al., 2022) https://arxiv.org/pdf/2210.03629 End
23. 柱1 設計原則 AIエージェントを迷わせないための特性 特性 詳細・具体的な考慮事項 機械可読・自己記述的・ セマンティック 機械可読で明確なドキュメント、メタデータ、エラーメッセージ、など。必須項目・制 約・デフォルトまで明示され、推測が要らないこと エラーの回復可能性 失敗しても立て直せること。何が・なぜ・どう直すかを機械可読な形で返すエラー設 計、リトライの指針、など 一貫性（予測可能性） 予測可能性がある命名規則、スキーマ構造、など 冪等性 何回実行しても結果が変わらないこと。AIエージェントは推論過程で同じ処理を繰 り返し実行(リトライ)する傾向があるため 発見可能性 見つけやすいこと。機械可読なAPI仕様の公開、APIカタログへの登録が有効 これらは、AIに対してだけでなく、人間にとっても本質的に重要な特性です
24. 柱1 設計原則 機械可読・自己記述的・セマンティックなAPI仕様 • OpenAPI Spec 機械可読なAPI仕様ドキュメント ◦ • 操作を一意に識別 操作の自己記述（何ができるかを明示） ◦ ◦ • OpenAPI、Postmanコレクション、GraphQL Schema、など operationId（操作の一意な識別子） summary / description（操作の意味・挙動説明） 入出力の構造（どう呼び、何が返るか） ◦ ◦ ◦ パラメータ・スキーマの型と制約 必須/任意の区別 サンプルデータ（example） 型・形式まで明示 サンプルで理解を助ける
25. 柱1 設計原則 エラー回復可能性のあるエラー エラー回復可能性のあるエラー情報の提供: ステータスコード, エラーメッセージ • • • HTTP標準のステータスコードを利用：400, 500… エラーの原因を明確かつ具体的な自然言語で説明 再試行、回避可能性など、次のアクションを判断できる情報を提供 Stripe APIのRate Limitエラー（HTTP ステータスコード : 429） Stripe API error handling https://stripe.com/docs/error-handling
26. 柱1 設計原則 一貫性（予測可能性）のあるAPI 一貫性（予測可能性）のあるAPIを提供することが、エージェントの正しい判断を支える • • AIエージェントの行動モデルはReAct的で、パターン・規則性に従い判断する 規則が崩れると、一つ学んだことを他に応用できず、APIを誤って扱いやすくなる 一貫性のパターンと効果： • 命名の一貫性: API探索・目的理解を助ける ◦ • 引数の一貫性: パラメータ設定の誤りを防げる ◦ • 悪例：あるAPIは uid、別のAPIは user_id エラー構造の一貫性: 後続アクション（リトライなど）の判断が容易になる ◦ • 悪例：/v1/users/{id} と /api/2/orders/{id} が混在 悪例：一方は {error: "..."}、他方は {code, message} レスポンス形式の一貫性: 結果の解釈と次の推論がスムーズになる ◦ 悪例：一方は配列を直接返し、他方は {data: [...]} で包む
27. 柱2：ガードレール 秩序を与える（Harness Engineering）
28. 柱2 ガードレール なぜ、ガードレールが必要なのか？ AIエージェントは自律的に動く。だが、その振る舞いは確率的で、常に予測できるとは限らない。しかも、 人間の認知を超えて高速・大量に実行される AIエージェントの3つの性質： • • • 自律的: 人の判断を介さず動く 確率的: 振る舞いは予測しきれない 高速・大量: 人のレビューが追いつかない AIは「増幅器（amplifier）」。強い組織を強くし、脆い組 織の弱点をあぶり出す。 制御システム（自動テスト・バージョン管理・速いフィー ドバック）がなければ、変更量の増加は そのまま"不安定さ"に直結する。 出典（脚注）： DORA「State of AI-assisted Software Development」2025 必要なのは、 逸脱を起こさせない環境＝検証可能な制約（テスト・型・権限…） ＝ ガードレール（Harness Engineering）
29. 柱2 ガードレール Harness Engineering ― 手綱を整える 要素 説明・例 テスト 期待される振る舞いを定義し、出力の正誤を機械的に判定する CI/CD 変更を自動検証し、問題があれば先へ進ませない関門 リンター 命名・書式・設計ルールへの違反を機械的に検出し、規約を明文化 型システム 入出力の構造を事前に制約し、不正な形式を実行前に弾く 権限・スコープ エージェントが「できること」の範囲を事前に絞る レートリミット・クォータ 高速・大量の実行を量の側から制限し、暴走を防ぐ 可観測性・監査 実行詳細を記録し、後からトレースできる状態にする 例：ユニットテスト、コントラクトテスト、E2Eテスト 例：プルリクエスト時の自動テスト実行、デプロイ前のゲートチェック 例：Spectral（OpenAPI検査）、ESLint、APIスタイルガイド自動チェック 例：OpenAPIスキーマ 例：OAuthスコープ、RBAC 例：同時実行数の制限 例：監査ログ、トレーシング
30. 柱2 ガードレール コントラクトテスト ― 仕様と実装の乖離を防ぐ APIが合意された「コントラクト」API仕様)通りに振る舞うかを検証するテスト なぜコントラクトテストが重要か？： • • 仕様と実装の乖離（APIドリフト） ⇒ エージェントの誤動作・ハルシネーション コントラクトテストは、APIドリフトを検知し、エー ジェントに届く前の壁になる コントラクト：合意された契約 OpenAPI Spec, GraphQL, Postman Collection etc. API コントラクト 参照 APIドリフトの例 • • • • • レスポンス構造の変更 必須フィールドの欠落 型の不整合 ステータスコードの変更 エラーメッセージの変更 API 利用者 参照 リクエスト レスポンス API 提供者
31. 柱2 ガードレール リンターでAPIスタイルガイドの自動チェック スタイルガイドの文書作成だけで終わらせず、CIで自動チェックできる状態にする APIスタイルガイド Spectralルール化 リンターで自動チェック 設計原則一覧を文書化 extends: ["spectral:oas"] Postmanのガバナンスルール検証例 ✓ パスは kebab-case 例: /user-profiles rules: path-kebab-case: description: パス命名を統一 severity: error given: $.paths[*]~ then: function: pattern functionOptions: match: "^/[a-z0-9-/{}/]+$" ✓ 全operationにsummary API利用者が意図を読める ✓ エラー形式を統一 code / message / details ✓ 認証方式を明記 security を必須化 ✓ 破壊的変更を検出 version / deprecation operation-summary: severity: warn given: $.paths[*][*] then: field: summary function: truthy 違反箇所を行単位で返す PR前に設計不整合を検出
32. 柱3：運用体制 継続的に保つ
33. 柱3 運用体制 品質問題は、品質に責任を持つ人・組織の不在に起因 社内APIの品質が低いのは、技術だけの問題ではない。品質に「責任を持つ人・組織」が定まっていないこ と、つまり、運用体制の問題が大きい。Axway社のレポートによると： 78 % 74 % 1/3 自社APIの数を把握してい ない 自社APIの20%が未管理 一元管理されているAPI 74%の企業が、自社APIの20%以 上が実質的に「管理されていない」と 認めている 全APIの3分の1のみが運用統括 チームによって管理されており、残り は各チームや外部に委ねられている 意思決定者の78%が、自社にAPI がいくつ存在しているのかを把握し ていない 引用元: The state of enterprise API maturity in 2024 Axway社) https://resources.axway.com/build-api-marketplace/ig-api-maturity-enterprises-5-key-stats-en のみ
34. 柱3 運用体制 守り続けるための仕組み ツールを導入するだけでは不十分。「誰が標準を決め、どう守り続けるか」——責任の設計と仕組み化こ そが鍵になる 例 説明 オーナーシップの明示 各APIに責任を持つチーム・人を必ず紐づける（所有者不明を作らない） 横断の推進役の設置 標準を定めるだけでなく、部門横断で浸透・調整を担う役割を設ける （Champion / プラットフォームチーム） ガイドライン作成 命名・認証・バージョニングなど、組織標準ガイドラインを作成し、文書化する プロセスの標準化 API登録の義務化（カタログは登録ルールがあって初めて機能する）、デザインレ ビュー、廃止プロセス（シャドーAPI対策）、など
35. 参考情報 チームトポロジーで捉え直すと 標準を中央から強制するのではなく、チームの役割として設計する チームトポロジーでの位置づけ Stream-aligned チーム APIを所有) オーナーシップの明示 横断の推進役（基盤提供） 横断の推進役（浸透・教育） Facilitating Enabling チーム (標準の浸透・教育) X-as-a-Service Platform チーム (共通基盤の提供) カタログ・ゲートウェイなど ガイドライン・プロセス標準化 ガイドライン・プロセスはチーム間の規約
36. 大切なこと   ３つの柱は、どれも一度の実 装で終わる作業ではない 変わり続ける技術や組織の中での 評価と改善を繰り返す 継続的なサイクル
37. Postman
38. Postman - 統合APIプラットフォーム • • APIライフサイクルの標準化、コラボレーション、ガバナンス、ガードレールを支援 組織全体でAPIの発見・再利用が可能となり、安全性と一貫したガバナンスの実現が可能 提供する機能・能力 実現できること APIライフサイクルの標準化 APIクライアント 設計 & モック ガードレール テスト自動化 ドキュメンテーション ガバナンスのシフトレフト モニタリング & オブザーバビリティ APIカタログ APIの可視化 エンタープライズ コントロール セキュリティ & ガバナンス APIスプロール (乱立)の抑制
39. プロダクト骨格（API）の品質を高めAXを支援 機械可読なAPI仕様・ドキュメント作成 型・スキーマの強制 設計原則 APIスタイルガイド遵守検証（リンター） 迷わせない コントラクトテスト APIシナリオ・リグレッションテスト ガードレール 秩序を与える APIセキュリティ・パフォーマンステスト API監視・可観測性検証 組織・チームコラボレーション支援 運用体制 継続的に保つ AXの３つの柱 APIカタログ構築 AX
40. クロージング
41. まとめ • なぜ、あなたのAPIは使われなくなるのか？ ◦ 答えはAXにある ― AIエージェントが迷わす製品を理解し、自律的に確実に操作 できるようにするための体験設計が十分ではないことが要因 • AX実現のために、３つの柱で、つくり・守り・保ち続けよ ◦ ◦ ◦ 1. 設計原則（つくる） 2. ガードレール（守る） 3. 運用体制（保ち続ける）
42. ありがとうございました @postman_japan
43. API 最新情報や Postman プラットフォームをもっと知りたい Postman オンライン ワークショップ 無料のハンズオン講習 Postman API Night Postman Launchpad API 関連トークのミートアップ https://postman.connpass.com ランチタイムの Postman 最新情報 https://postman.connpass.com https://postman.connpass.com Postman Japanコミュニテ Discord https://discord.gg/G4SQWDDqVa Postman Japan Youtubeチャンネル https://www.youtube.com/PostmanJapan @postman_japan Postman Qiita https://qiita.com/organizations/postmanjapan Postman Japan X https://x.com/postman_japan