AIエージェントワークスペースと他のシステムとのインテグレーションが期待通りに動作しない場合は、トラブルシューティングが必要になる可能性があります。この記事では、インテグレーションに関する問題を特定するために実行できる、いくつかのトラブルシューティング手順について説明します。
この記事では、次のトピックについて説明します。
- インテグレーションビルダーでインテグレーションをテストする
- リクエストパラメータの一致を確認する
- 会話ログでセッションパラメータを確認する
- 失敗シナリオで生の値を出力する
- HTTPステータスコードを確認する
- 対話内の技術的エラーを調査する
関連記事
インテグレーションビルダーでインテグレーションをテストする
インテグレーションのトラブルシューティングを行う際の最初のステップとして、インテグレーションビルダーでテストを行います。レスポンスが返されていること、およびセッションパラメータに正しいデータが含まれていることを確認してください。
リクエストパラメータの一致を確認する
インテグレーションビルダーで使用しているリクエストパラメータは、URLクエリ、ボディ、ヘッダーのいずれで使用する場合も、ダイアログで取得されたものと完全に一致している必要があります。
以下の項目を確認します。
- タイプミスがないこと。
- 対話のどの段階でもパラメータのスペルや名前を更新した場合、インテグレーションの設定でも同様に変更すること。
- 大文字と小文字が完全に一致していること。パラメータでは大文字と小文字が区別されます。
ヒント：すべてのリクエストパラメータおよびセッションパラメータについては、lowerCamelCase や snake_case などの一貫性のある命名規則を採用することをお勧めします。
会話ログでセッションパラメータを確認する
セッションデータなどの詳細については、「会話ログ」を参照してください。タグでフィルタリングすることで、APIを使用している会話を検索できます。会話でAPIが使用されている場合は、その会話を検索できます。
会話ログ画面の左上にある「フィルターを追加」をクリックします。
左側のメニューから「ラベル」を選択します。
ここでは、インテグレーションの名前や、成功、失敗、APIエラーの有無といったシナリオに基づいてフィルタリングできます。
インテグレーションビルダーで作成されたインテグレーションについては、先頭に「API」という接頭辞が付き、その後にインテグレーション名、最後にシナリオ名が続きます。
以下の「API-Chloe Demo:Apple Cart-Success」のスクリーンショットの例では、次のようになっています。
- API = プレフィックス
- Chloe Demo:Apple Cart = インテグレーション名
- Success = シナリオ名
インテグレーションをすばやく確認するには、会話ログ上のタグアイコンにカーソルを合わせて、その会話に関連付けられているタグを確認する方法もあります。
APIでエラーが発生した会話だけを確認したい場合は、「ラベル」の検索で「apiError」を検索します。
次に、その会話を選択して詳しく確認します。
会話内で、セッションデータに何が含まれているかを確認できます。
これを行うには、右上の「詳細」をクリックします。
これをクリックすると、「会話の概要」が表示されます。次に、「セッションデータ」をクリックします。
これで、チャット内のセッションデータを確認できます。この例では、画面下部にAPIインテグレーションから取得されたセッションパラメータが表示されています。
会話ログで対話を確認する
セッションにセッションパラメータが存在するかをすばやく確認するには、ダイアログを通じてAIエージェントメッセージにログ出力できます。この操作は、ステージング環境で対話をテストする際に実行するのが最も安全です。または、インテグレーションが本番環境で稼働している場合は、テスト中に対話を保存しないように注意してください。
以下のAIエージェントメッセージでは、テスト時にパラメータを確認できるよう、セッションパラメータがログ出力されています。
障害発生時の生データを出力する
data を $string(data) 関数でラップして、レスポンス内のすべてのデータを文字列化します。これをテスト時の失敗シナリオでログ出力することで、何が返されているかをすばやく確認できます。
HTTPステータスコードを確認する
インテグレーションのテストを行う際は、返されるHTTPステータスコードを必ず確認してください。右側のレスポンスに、statusCode キーとして表示されます。
2xx：成功
-
200 OK：リクエストは正常に処理され、サーバーから期待通りのデータが返されました。
- これは、インテグレーションテストでの理想的な応答です。
4xx：クライアントエラー
この範囲のエラーは、通常、インテグレーションビルダーに送信されたリクエストに問題があることを示しています。
-
400 Bad Request：構文が不正であるか、パラメータが不足しているため、サーバーはリクエストを理解できませんでした。
- リクエストのペイロードにエラー、情報が入力されていないフィールド、または不適切なフォーマットがないか確認してください。
-
401 Unauthorized：認証が必要ですが、提供されていないか、認証が無効です。
- APIキー、トークン、またはその他の認証資格情報を確認してください。認証ヘッダーも再確認してください。
-
403 Forbidden：サーバーはリクエストを理解しましたが、その承認を拒否しました。
- IPアドレスが許可リストに登録されているか、またはAPIのアクセス権限を確認してください。
-
404 Not Found：リクエストされたリソースがサーバー上に見つかりませんでした。
- URLまたはエンドポイントを確認してください。使用したパスが正しいこと、リソースが存在することを確認してください。
5xx：サーバーエラー
この範囲のエラーは、通常、バックエンドサーバーでの問題を示しています。
-
500 Internal Server Error：バックエンドサーバーで何らかの問題が発生したことを示す一般的なエラーです。
- 詳細なリクエスト情報を添えてバックエンドチームに連絡し、さらなるデバッグを行ってください。
-
502 Bad Gateway：サーバーがアップストリームサーバーから無効なレスポンスを受け取りました。
- これは、バックエンドの内部サービスや依存関係に問題があることを示している場合が多いです。
-
503 Service Unavailable：サーバーが現在リクエストを処理できない状態です。過負荷やメンテナンスが原因である可能性があります。
- しばらくしてから再試行し、予定されたダウンタイムがないか確認してください。
-
504 Gateway Timeout：サーバーがアップストリームサーバーからレスポンスを適時に受け取れませんでした。
- バックエンドサービスが稼働していることを確認し、レイテンシーの問題がないか確認してください。
対話内の技術的エラーを調査する
技術的なエラーが発生した旨のメッセージが表示されることがあります。技術的なエラーには、以下のようなテキストが表示されます。
「大変申し訳ございません。技術的な問題が発生しているようです。まもなく復旧できるよう努めています。」
この場合、問題はインテグレーション自体に関連するものではなく、対話のエラーである可能性が高いです。以下のヒントをご参考にしてください。
- 対話を確認し、フローがインテグレーションに到達していることを確認します。確認にはバッファメッセージを使用し、ボタン機能の混在、リンク切れ、循環参照などの問題がないか確認してください。
- 必要なパラメータがすべて指定されているか確認します。必要なパラメータが欠けていると、インテグレーションが実行される前にエラーが発生します。
- カードやカルーセルなどの動的コンテンツについて、すべてのフィールドに値が入力されていることを確認します。未定義、空白、またはnullの値があると、これらのコンポーネントが正常に動作せず、エラーの原因となる可能性があります。