Postman Agent Modeのベストプラクティス

Agent Modeとは？

Agent Modeは、APIワークフローを自動化し、効率化するためのPostmanのAIアシスタントです。主にPostman内のチャットインターフェースとして動作し、プラットフォーム全体と緊密に統合されています。複数の機能やタブを手作業で行き来する代わりに、実行したいことを伝えるだけで、Agent Modeがユーザーに代わって処理を進めます。API仕様の下書き、テストの作成、エラーのデバッグ、ドキュメントの更新、ワークフローの管理などを、設定された権限とガバナンスの範囲内で、実際のPostmanアセットに対して実行できます。

Agent Modeは、手作業で行うワークフローを補完します。これまでどおりリクエストをタブで開いて手動で編集することもできますが、一般的なワークフローの多くは、Agent Modeのインターフェース内だけで最初から最後まで進められるようになりました。

Agent Modeの主な機能

機能	説明
リクエストのデバッグ	リクエスト、環境、認証設定のコンテキストをすべて確認し、401や500などのエラーの原因を診断する
APIテスト	複数のコレクションにわたってテストスクリプトを生成、更新、標準化する
Documentation	APIドキュメントを自動的に改善または生成する
コレクション管理	コレクションやフォルダーを再編成、リファクタリング、統合する
API仕様とスキーマ	OpenAPI仕様とスキーマを分析して更新する
Git統合	Postmanアセットとソースコードファイルの両方を参照して判断する
MCPによる拡張	JiraやGitHubなどの外部システムに接続する
Insightsとモニタリング	API Catalogの情報を確認し、障害を監視して、カバレッジを評価する
エンタープライズガバナンス	RBAC、ガードレール、シークレットスキャン、MCPサーバーの制御を利用する

Agent Modeを始める

Agent Modeへのアクセス

Agent Modeを開く方法は2つあります。

コンテキストバー：任意のワークスペースで、右側のコンテキストバーにあるAgent Modeアイコンをクリックする。自然言語で依頼内容を入力すると、Agent Modeが内容を分析・推論し、ユーザーに代わって操作を実行する。
その場で［Ask AI］を使用：レスポンスボディ、テストスクリプト、スキーマの一部を選択して右クリックし、［Ask AI］を選択する。選択した内容がコンテキストとしてAgent Modeに直接送られるため、チャットに手作業でコピーしなくても、対象を絞って詳しく分析できる。

コンテキストに基づいて作業する

Agent Modeは、対象や状況を具体的に伝えることで、より適切に動作します。次の方法でコンテキストを指定できます。

対象の項目をチャットパネルに直接ドラッグ＆ドロップする。
@コマンドを使って、特定のコレクション、フォルダー、リクエスト、環境を指定する。

コンテキストを指定することで曖昧さが減り、Agent Modeがより正確に判断できるようになります。

ヒント：会話の対象を明確にしましょう。より高度に活用する場合は、会話の対象となるPostmanアセットを明示すると、正確な結果をすばやく得られます。一般的な質問をするのではなく、確認が必要なリクエスト、API仕様、環境を具体的に指定します。

たとえば、「認証エラーが発生するのはなぜですか？」と質問する代わりに、「@MyAPI-Collection > Auth Endpoints > POST /login — 'staging' 環境を使用すると401が返されるのはなぜですか？」と質問します。

Agent Modeの主なワークフロー

情報の探索と把握

Agent Modeは、UIのどこを確認すればよいか分からない場合に特に便利です。コレクションやモニターを手作業で探す代わりに、まず質問することから始められます。目的の情報がどこにあるかを探すのではなく、知りたいことを伝えるだけで作業を始められます。Agent Modeは、組織のPostman環境全体を検索して、関連する情報を見つけることができます。

情報探索に使えるプロンプトの例：

「このワークスペースのテストカバレッジはどの程度ですか？」
「ドキュメントがないコレクションはありますか？」
「Payments APIは最新の状態ですか？それとも非推奨に設定されていますか？」
「/orders エンドポイントでエラーが発生し始めたのはいつですか？また、どのモニターが検出しましたか？」
「このワークスペース内の複数のコレクションに、重複するリクエストはありますか？」

複雑な変更を実行

Agent Modeの大きな特長の1つは、複数のステップからなる変更をまとめて実行できることです。コレクションの再編成、重複するスクリプトの統合、テストの標準化、認証ロジックの共有スクリプトへの移動、API仕様の再利用可能なコンポーネントへのリファクタリングなどを行えます。数十ものリクエストを手作業で編集する代わりに、どのように変更したいかを伝えるだけで、Agent Modeに実行を任せることができます。

たとえば、コレクションを再編成する場合：「『E-Commerce API』コレクションを、HTTPメソッド別ではなく、リソース（ユーザー、注文、商品、決済）ごとにリクエストをグループ化するよう再編成してください。」

Agent Modeは現在のコレクション構造を読み取り、すべてのリクエストとそれぞれに対応するリソースを特定します。そのうえで、リソースごとに新しいフォルダーを作成し、リクエストを適切なフォルダーに移動します。既存のスクリプト、ヘッダー、環境への参照はすべて維持されます。

リクエストのデバッグ

Agent Modeは、リクエストが失敗する原因の特定に特に役立ちます。失敗したリクエストをコンテキストとして指定すると、問題を順を追って診断し、推奨される修正方法を確認できます。たとえば、次のように質問します。たとえば、次のように質問します。

「@POST /api/v2/orders — このリクエストでは401 Unauthorizedが返されます。トークンは「Production」環境に設定されています。何が問題ですか？」

Agent Modeは、選択した環境のトークン変数が期限切れまたは空になっている、親フォルダーから異なる設定の認証を継承している、Bearerトークン認証を使用しているものの変数にBearerプレフィックスが含まれていない、といった原因を特定できる場合があります。

APIのテストとドキュメント作成

Agent Modeを使うと、Postmanコレクションのテストをすばやく生成し、ドキュメントを改善できます。

テストの生成：「@Payments-Collection のすべてのリクエストに対して、包括的なテストを生成してください。各テストでは、ステータスコード、レスポンスタイム（500ミリ秒未満）、レスポンススキーマがOpenAPI仕様に準拠していることを検証してください。」
ドキュメントの改善：「@User-API-Collection のドキュメントを確認してください。説明がないリクエストやパラメーターには説明を追加し、すべての例が最新の状態になっていることを確認してください。」

Agent Modeの設定とカスタマイズ

操作と安全性（Auto-Run）

Agent Modeには、ツールによる操作を自動的に実行するか、実行前にユーザーの承認を必要とするかを指定する「Auto-Run」設定があります。

設定	動作	適した用途
Auto-Run On	承認済みの操作をAgent Modeが中断せずに実行	すばやいイテレーション、信頼できる環境、定型的な作業
Auto-Run Off	各操作をユーザーが個別に確認して承認	機密性の高い環境、操作を細かく確認したい場合、Agent Modeの使い方を学ぶ場合

注意：Auto-Runをオンにしていても、シェルコマンドの実行など、機密性の高い操作には引き続きユーザーの承認が必要です。ほとんどのワークフローでは、Auto-Runを有効にしておくことで、実行速度と操作のコントロールをバランスよく両立できます。本番環境など特に慎重な操作が必要な環境で作業する場合や、Agent Modeが各ステップで何を行うのかを詳しく確認したい場合は、Auto-Runを無効にします。

モデルの選択

ほとんどのユースケースでは、「Auto」によるモデル選択が適しています。タスクに応じて、各モデルの特性を考慮しながら適切なモデルを選択します。より細かく指定したい場合は、Agent Modeでモデルを手動で選択することもできます。新しいモデルがリリースされると、順次追加されます。

モデルの種類	特長	適した用途
大規模モデル（例：Opus）	より高度な推論、より詳細な説明	複雑なリファクタリング、大幅な構造変更、複数のステップからなる変更
小規模モデル（例：GPT-5 Mini）	より高速なレスポンス、コスト効率が高い	軽微な編集、すばやいデバッグ、定型的な調整

ローカルファイルとGit統合

Agent Modeは、PostmanのLocal File SystemおよびネイティブのGitサポートと緊密に統合されています。ワークスペースを「Local mode」で接続すると、Agent ModeはPostmanアセットと関連するソースコードファイルの両方を参照して判断できます。これにより、OpenAPI仕様、コレクション、実装コードを相互に確認しながら更新できます。

たとえば、「/api/v2/users のOpenAPI仕様を更新して、新しい「role」フィールドを追加しました。対応するコレクションのリクエストとバックエンドの実装コードを確認し、不整合がないか調べてください。」と質問できます。

Agent Modeは更新されたOpenAPI仕様を読み取り、コレクション内の/usersエンドポイントのリクエストを確認します。さらに、Git統合を通じて関連するソースコードファイルを調べ、API仕様、コレクション、実装の間に不整合があれば指摘します。

設定が必要：この機能を利用するには、ワークスペースを「Local mode」に切り替え、Git統合が正しく設定されていることを確認してください。

MCPサーバーでAgent Modeの機能を拡張

Agent Modeは、MCP（Model Context Protocol）サーバーを通じて機能を拡張し、外部システムと統合できます。

Jira統合：リクエストのデバッグ中にバックエンドの実装が不足していることが分かった場合は、次のように指示できる。「POST /api/v2/refunds エンドポイントが501 Not Implementedを返しています。再現手順、期待される動作、関連するAPI仕様のセクションを含むJiraチケットをバックエンドチーム向けに作成してください。」Agent Modeは、接続されたAtlassian MCPサーバーを使って、Postman内から直接Jiraの課題を作成する。
GitHub統合：次のように指示できる。「GitHub MCPサーバーを使って、バックエンドリポジトリから /api/v2/orders エンドポイントの実装を見つけ、ページネーションが正しく処理されているか確認してください。」Agent Modeはリポジトリを検索してエンドポイントの実装を特定し、コードを確認する。リポジトリがローカルにクローンされていなくても実行できる。

エンタープライズのガバナンスとセキュリティ

Agent Modeは、組織で設定されたガバナンスの範囲内で動作します。エンタープライズプランでは、チーム全体でAI機能を管理するための詳細な制御を設定できます。

Agent ModeのデータアクセスとRBAC

Agent Modeは、Postmanの各リソースに対するユーザーの権限をそのまま引き継ぎます。これにより、Agent Modeが操作できる範囲は、ユーザー単位のロールベースアクセス制御（RBAC）でユーザー本人に許可されている範囲と一致します。

ワークスペース：ユーザーにアクセス権があるワークスペースにアクセスできる。
コレクション：ユーザーのロールに応じて、コレクションを読み書きできる。
環境：ユーザーのアクセスレベルで許可されている環境にアクセスできる。
仕様：ユーザーが表示または編集できるAPI仕様にアクセスできる。
Gitと接続されたアセット：ユーザーのGit設定を通じてアクセス可能なファイルにアクセスできる。

重要な原則：Agent Modeがユーザーの権限を超えて操作することはありません。認証されたユーザーに許可されている操作のみを実行できます。認証されたユーザーが権限を持つ操作のみを実行できます。

ステップ1：AIを利用できるユーザーやチームを制限

管理者は、Agent Modeをいつでも有効または無効にでき、特定のユーザー、グループ、またはエンタープライズ全体に利用を許可できます。Postmanの管理パネルで［Team Settings ＞ AI］に移動し、［Manage access］で［Selected users, teams or groups］を選択して、アクセスを許可するチームまたはユーザーを追加します。

PostmanのAI機能にアクセスできるユーザーやチームを管理するためのオプションが表示されたAIアクセス設定

ステップ2：Guardrailsを有効にする

Guardrailsは、すべてのAIへのリクエストとレスポンスにコンテンツモデレーションポリシーを適用します。

PII（個人識別用情報）、認証情報、機密性の高い社内情報などの機密データが外部に露出するのを防ぐ。
すべてのAIとのやり取りにコンテンツモデレーションポリシーを適用する。
チームやアプリケーション全体に一貫したガバナンスルールを適用する。

Guardrailsを有効にすると、PII Redactionによってメールアドレスなどの機密情報が検出され、LLMに送信される前にプレースホルダーへ置き換えられます。実際のPIIを公開することなく、Agent Modeにはタスクの実行に必要なコンテキストが提供されます。

［Secret Scanner］、［PII Redaction］、［MCP Server］のポリシー制御が表示された［Guardrails］設定

ステップ3：シークレットスキャンを有効にする

Secret ScannerはPostmanアプリケーション内でローカルに動作し、定義されたシークレットのパターンを検出して、機密性の高い認証情報がユーザーのマシンから外部に送信されるのを防ぎます。

ユーザーがクライアントからAgent Modeに送信しようとするシークレットを検出する。
シークレットはクライアント側でマスキングされ、ユーザーの環境外には送信されない。
組織固有のシークレットに合わせて、シークレットスキャン用のカスタム正規表現パターンを定義する。

重要：組織固有の形式を持つシークレット（社内APIキー、データベース接続文字列、サービストークンなど）を漏れなく検出できるよう、それぞれに対応するカスタム正規表現パターンを定義してください。

ステップ4：サードパーティのMCPサーバーを選択する

Organizationsでは、ユーザーがAgent Modeで設定できるサードパーティのMCPサーバーを制御できます。［Team Settings］＞［AI］＞［Guardrails］に移動し、［MCP Policy］で次のいずれかを選択します。

All MCP Servers：任意のMCPサーバーへの接続を許可する。
Specific MCP Servers only：管理者が定義した許可リストにあるMCPサーバー（Atlassian、Jira、GitHub、社内ツールのサーバーなど）に接続を制限する。

セキュリティを強化するための追加の制御

成熟したAIガバナンスでは、AIもSDLCに参加する開発主体として扱います。AIが生成した変更にも、人が作成した変更と同じ検証プロセスとリリースまでのプロセスを適用します。

制御	説明
自動検証	AIが生成した変更にも、人が作成した変更と同じ自動検証を適用する
CI/CDの適用	人が作成したかAIが生成したかにかかわらず、すべての変更をCI/CDパイプラインに通す
Gitベースのレビュー	AIが生成したコードにも、プルリクエストによるレビューと承認を適用する
ガバナンスルールセット	人とAIのすべての作業に一貫したルールを適用する
経営層向けレポート	組織全体でAIがどのように利用され、どのような影響があるかを把握する
会話の削除	Agent Modeの会話履歴をユーザーが削除できる

実践的な例とプロンプトのパターン

デバッグ

「@POST /api/v2/checkout — このリクエストでは、{ 'error': 'internal_server_error' } というレスポンスボディとともに500エラーが返されます。リクエストボディ、ヘッダー、環境変数を確認してください。何が原因として考えられますか？」
「'staging' 環境と 'production' 環境を比較してください。一方にだけ存在する変数はありますか？」

APIテスト

「@Orders-Collection のテストを実行し、失敗しているテストをまとめてください。それぞれについて、考えられる原因を説明し、修正方法を提案してください。」
「@MyAPI-Collection のすべてのテストを確認してください。非推奨の pm.test() 構文を使用しているテストは現在の形式に置き換え、命名規則が統一されていることを確認してください。」

Documentation

「@User-API のOpenAPI仕様を使って、すべてのエンドポイントのリクエストとレスポンスの例を生成してください。実際の利用を想定したサンプルデータを含め、コレクションのドキュメントに追加してください。」

リファクタリング

「@Payment-API でAuthorizationヘッダーを個別に設定しているすべてのリクエストを見つけてください。認証ロジックをコレクションレベルのプレリクエストスクリプトに移動し、個々のリクエストから削除してください。」
「@Inventory-API のOpenAPI仕様をリファクタリングしてください。重複しているスキーマ定義を抽出し、#/components/schemas 配下の再利用可能なコンポーネントにしてください。」

ガバナンス

「このワークスペースのエンドポイントのうち、テストが用意されている割合はどのくらいですか？テストされていないエンドポイントを一覧にしてください。」
「今週、失敗率が最も高いモニターはどれですか？エラーが発生し始めたのはいつですか？」

クイックリファレンスチェックリスト

コンテキストを指定：@による参照やドラッグ＆ドロップを使って、会話ごとに対象を明確にする。
具体的に指示：問題だけでなく、どのように変更したいかを具体的に伝える。
まず確認：判断に迷う場合は、変更を加える前にAgent Modeに状況を確認させる。
［Auto］でモデルを選択：複雑で複数のステップからなるリファクタリングの場合にのみ、モデルを手動で変更する。
［Auto-Run］を有効にする：機密性の高い環境でのみ無効にする。
Gitに接続：複数の対象を横断して確認できるように、［Local mode］に切り替える。
MCPサーバーを追加：Jira、GitHubなどのツールを接続し、連携したワークフローを実現する。
ガバナンスを設定：チームに展開する前に、アクセス制御、［Guardrails］、シークレットスキャンを設定する。
その場で［Ask AI］を使用：選択した内容を右クリックし、作業中の画面を離れることなく、対象を絞ってサポートを受ける。

使いながら理解するのが一番です。Postman Agent Modeについて詳しくはこちら →