Connect AI AgentsのログをCloudWatch Logs Insightsで調査するクエリ集

はじめに

こんにちは！廣田です。
今回は Amazon Connect AI Agents（旧 Amazon Q in Connect）が出力するログを CloudWatch Logs Insights で調査するためのクエリテンプレートをまとめてみました！

業務で AI Agents の挙動を調査する場面があり、「どのコンタクトでどんなプロンプトが投げられて、何が返ってきたのか」を素早く突き止めたいなと思っていました。毎回ゼロからクエリを書いていたら大変なので、よく使うパターンを整理してテンプレ化しています。

この記事のクエリはコピペで使えるので、同じように Connect AI Agents の調査をする方の手助けになれば嬉しいです。

環境・前提条件

項目	内容
サービス	Amazon Connect AI Agents（旧 Amazon Q in Connect）
ロググループ	/aws/connect/q-in-connect（環境に合わせて変更）
クエリ実行画面	CloudWatch Logs Insights

事前に Connect AI Agents のログを CloudWatch Logs に出力する設定が必要です。
設定手順は以下のクラスメソッドさんの記事がとても分かりやすいので、こちらを参考に有効化しておいてください！

• Amazon Q in Connect の動作ログを CloudWatch Logs に出力する

配信設定が完了すると、指定したロググループ（例: /aws/connect/q-in-connect）にログが流れ始めます。

やったこと

実際の案件環境で、よく使うクエリパターンを5つに整理しました。
「セッションを特定する → セッションの中身を見る → 詳細を深掘りする」 という調査フローに沿って並べています。

1. 直近のセッション一覧を取得する

まずは直近で発生したセッションを一覧化し、調査対象を特定するクエリです。

fields @timestamp, session_id, session_name, event_type
| filter event_type = "TRANSCRIPT_CREATE_SESSION"
| sort @timestamp desc
| limit 50

補足: session_name には Amazon Connect のコンタクト ID が格納されます。
コンタクト ID が分かっている場合は session_name で直接フィルタすればピンポイントに探せます！

2. コンタクトIDからセッションの全ログを取得する

特定の通話・チャットに紐づく AI Agent のイベントを時系列で全部見たいときに使います。

fields @timestamp, event_type, session_id, completion, model_id, prompt_type
| filter session_name = "<コンタクトID>"
| sort @timestamp asc

「お客さまから〇〇という問い合わせがあって、AI Agent はどう応答したのか」を追うときに、これ一つで流れが見えるので便利でした。

3. セッションIDからセッションの全ログを取得する

すでにセッション ID が判明している場合は、こちらの方がシンプルです。
クエリ2との違いは、intent や recommendation_id も拾っているので、より詳細を見るのに向いています。

fields @timestamp, event_type, completion, model_id, prompt_type, intent, recommendation_id
| filter session_id = "<セッションID>"
| sort @timestamp asc

4. LLM呼び出しの詳細（プロンプト・レスポンス）を確認する

AI Agent の回答品質を調査するときに最重要なクエリです。
特定セッションで実際に Bedrock モデルへ送られたプロンプトと応答を確認できます。

fields @timestamp, prompt_type, model_id, parsed_response, completion
| filter session_id = "<セッションID>"
| filter event_type = "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION"
| sort @timestamp asc

補足: prompt フィールドにはシステムプロンプト全文が含まれるためかなり長いです...。
プロンプトの中身まで確認したいときだけ fields に prompt を追加するのがおすすめです。

5. レスポンス時間を推定する（性能評価用）

顧客の発話から AI Agent が LLM 呼び出しを完了するまでの時間を計測するクエリです。
実応答時間の近似値として、性能評価やレイテンシー調査に使えます。

fields @timestamp, event_type
| filter session_id = "<セッションID>"
| filter event_type in ["TRANSCRIPT_UTTERANCE", "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION"]
| stats min(@timestamp) as query_at, max(@timestamp) as result_at by session_id
| fields (result_at - query_at) / 1000 as response_sec
| sort response_sec desc

本検証では「プランを作成してください」という発話に対し、約 19.5 秒のレイテンシーを確認できました。

ハマったポイント

min/max は「最初の発話」と「最後のLLM呼び出し」の差になる

クエリ5（レスポンス時間推定）で気をつけたいのが、1セッション内に複数ターンある場合の挙動です。
min(@timestamp) と max(@timestamp) だと、セッションの最初の発話と最後の LLM 呼び出しの差を計測することになるので、各ターンごとの正確なレスポンス時間ではない点に注意が必要です。

各ターンを厳密に測りたい場合は、

• 時系列クエリ（クエリ3など）で目視確認する
• Athena など外部処理に流して順次差分を取る

のいずれかをおすすめします。

prompt フィールドの取り扱い

クエリ4の補足にも書きましたが、prompt フィールドはシステムプロンプト全文を含むので、デフォルトで fields に入れるとログ画面が一気に見づらくなります...。
プロンプトの中身まで深掘りしたいときだけ fields に追加する運用が良さそうです。

結果

調査フローとして、以下のような流れで使い分けています。

① コンタクトIDまたは発生時刻を確認
        ↓
② クエリ1 でセッションを特定
        ↓
③ クエリ2 or 3 でセッション全体の流れを確認
        ↓
④ 必要に応じてクエリ4で LLM 呼び出しの詳細を深掘り
        ↓
⑤ 性能評価が必要ならクエリ5でレスポンス時間を計測

長期保存が必要な場合

CloudWatch Logs はデフォルト保持期間を超えると削除されてしまうので、長期間ログを残したい場合は以下のいずれかを検討すると良さそうです。

• CloudWatch Logs のエクスポート機能で定期的に S3 へ出力
• S3 に保存したログは Athena で session_id ベースのクエリが可能

まとめ

今回は Connect AI Agents のログを CloudWatch Logs Insights で調査するためのクエリ集をまとめました。

普段からよく使うパターンをテンプレート化しておくことで、いざ障害調査や挙動確認が必要になったときにスムーズに動けることを実感しました。特にプロンプトとレスポンスを直接見られるクエリ4は、AI Agent の挙動が想定と違うときに「そもそも LLM に何を投げているのか」を確認できるので、心強いです。

今後も Connect AI Agents 周りで便利なクエリを見つけたら、追記していきたいと思います！

最後まで読んでいただき、誠にありがとうございました。