開発チームがClaude CodeやCursorのようなAIコーディングアシスタントを使用している場合、Pendoのsetup-agent-analyticsスキルを使用すると、コードベースにtrackAgent()呼び出しを手動で追加する代わりに、Conversations APIの実装を自動化できます。
このスキルはプロジェクトをスキャンし、AIエージェントやプロジェクトフレームワークを検出し、プロンプト、応答、訪問者の反応に関する適切な追跡コールを追加します。クライアント側およびサーバー側の両方の実装をサポートしており、環境に基づいて適切な方法を選択します。
前提条件
スキルを使用する前に、以下の点を確認してください。
- Claude CodeやCursorが開発環境にインストールされ、実行されていること。
- クライアント側の実装では、Pendo Web SDKがアプリケーションにインストールされ、ブラウザのランタイムで
window.pendoが利用可能であること。 - サーバー側で実装する場合、エージェントが関連付けられているアプリケーションのトラッキングイベント共有シークレット。取得手順については、「サーバー側での会話イベントの送信」を参照してください。
- PendoにAIエージェントがセットアップされ、会話全体が有効化されます。設定手順については、「PendoでAIエージェントを追加および設定する」を参照してください。
- エージェントIDの使用準備が整いました。確認するには、［プロダクト］>［エージェントアナリティクス］に移動し、エージェント名の横にある設定（歯車）アイコンを選択します。
スキルをインストールする
setup-agent-analyticsスキルファイルをダウンロードし、お好みのAIコーディングアシスタントに追加します。インストール手順については、お使いのツールのマニュアルを参照してください。以下はその例です。
スキルを実行する
AIエージェントを含むプロジェクトのルートディレクトリで、AIコーディングアシスタントを開きます。このスキルは2つの方法で実行できます。
- スラッシュコマンド
/setup-agent-analyticsを使用します。 - アシスタントに直接スキルを使用するように指示します（例：「
setup-agent-analyticsスキルを使用して、AIエージェントにPendoトラッキングを組み込んでください」）。
エージェントIDが準備できている場合は、それを引数として渡してください。
/setup-agent-analytics agent_abc123アプリケーションに複数のAIエージェントがある場合は、複数のエージェントIDをスペースで区切って渡します。スキルは発見した順にエージェントに割り当てます。
/setup-agent-analytics agent_abc123 agent_def456エージェントIDをまだお持ちでない場合は、引数なしでスキルを実行できます。このスキルは、後で置き換えるプレースホルダー値（YOUR_AGENT_ID）を使用します。
スキルが実行する内容
このスキルは3つのフェーズで実行されます。フェーズ2とフェーズ3の間には一時停止があり、コードの変更を行う前に、ユーザーが結果を確認できるようになっています。
フェーズ1：プロジェクトフレームワークを検出する
このスキルは、プロジェクトのフレームワークを識別し、エージェントの検索場所や、サーバー側レンダリングの境界など、環境固有の考慮事項の処理方法を決定します。また、環境に応じてクライアント側かサーバー側の運用かを決定します。
フェーズ2：AIエージェントを検出する
スキルはLLM SDKの使用状況（OpenAI、Anthropic、Google AI、LangChain、Vercel AI SDKなど）をスキャンし、インポートをトレースして会話オーケストレーションレイヤーを見つけます。会話オーケストレーションレイヤーは、チャットセッションを管理し、ユーザー入力を処理し、AIレスポンスを返すコンポーネントまたはサービスです。
スキルは、検出したエージェントごとに以下の情報を報告します。
- エージェントの名前と説明。
- メインのオーケストレーションファイル。
- LLMプロバイダー。
- 計測方法（クライアント側またはサーバー側）。
- プロンプトが送信されるエントリーポイント。
- レスポンスを完成させるレスポンスハンドラー。
- リアクションを収集するフィードバックハンドラー（該当する場合）。
- チャット入力ボタンと送信ボタン（クライアント側のみ）用のCSSセレクター。
このスキルは、使用されているモデル、提案されたプロンプト、ツール呼び出し、ファイルアップロードなどのオプションメタデータをコードベースから検出し、利用可能な場合は追跡用の呼び出しに含めます。
確認する前に、これらの調査結果を慎重に検討してください。このスキルはフェーズ3に進む前にあなたの承認を求めます。
フェーズ 3：trackAgent()による計測
調査結果を確認した後、このスキルはコードベースに計測機能を追加します。
- 共有ユーティリティファイル（
src/utils/pendo.tsなど）にヘルパー関数を作成します。このヘルパーは、SSR環境向けにトラッキング呼び出しをガードでラップし、コンテンツを500文字に切り詰め、サイレントエラーを処理することで、アナリティクスがプロダクトに影響を与えないようにします。 - 各エージェントの送信ハンドラーにプロンプト追跡機能を追加し、API呼び出しの前に
promptイベントを発生させます。 - 各エージェントの応答が完了したとき（ストリーミングが終了した後、または応答が解決された後）、応答追跡機能を追加し、
agent_responseイベントを起動します。 - エージェントにフィードバックUI（サムズアップやサムズダウンなど）がある場合、リアクション追跡機能を追加し、
user_reactionイベントを発火します。 - 会話IDとメッセージIDを管理します。このスキルでは、既存の会話IDまたはセッションIDが使用可能な場合はそれを再利用し、使用不可能な場合は
crypto.randomUUID()を使用して生成します。会話IDは、セッション内のすべてのメッセージにわたって保持されます。メッセージIDは各メッセージごとに固有です。
運用後、スキルは追加したすべてのトラッキングコール、どのファイルと関数、どのエージェントIDを使ったかを示す要約表を表示します。
重要：エージェントIDを指定せずにスキルを実行した場合は、デプロイする前にコードベース内でYOUR_AGENT_IDを検索し、各インスタンスをエージェントの設定から取得した実際のエージェントIDに置き換えてください。プレースホルダーIDはPendoにデータを送信しません。
実装を検証する
スキルの実行が完了したら、変更内容をデプロイし、データがPendoに正しく取り込まれていることを確認してください。まず、Pendo Web SDKがロードされている（またはサーバー側の設定がアクティブになっている）開発環境でAIエージェントと対話することから始めます。プロンプトを提出し、返答を待ち、エージェントが支持すればフィードバックを提供しましょう。
次に、次のいずれかの方法を使用して、データがPendoに届いていることを確認します。
-
Pendoデバッガーを使用してイベントを確認する。ブラウザの開発者コンソールを開き、
pendo.enableDebugging()を実行して、［イベント］タブを開きます。［イベントログの開始］を選択し、エージェントにプロンプトを送信してください。イベントログにpromptとagent_responseイベントが表示されていることを確認します。イベントが表示されるまで、最初の操作から最大15分かかる場合があります。デバッガーの使用方法の詳細については、「エージェント設定のテスト」を参照してください。 - ［イベントの生データ］タブを確認する。生イベントを表示する権限がある場合は、Pendoの右上隅にある［設定］>［サブスクリプション設定］>［アプリケーション］に移動し、アプリを選択して［生イベント］タブを開くことで、イベントがPendoに届いていることを確認することもできます。
- エージェントアナリティクスでデータを確認する。会話データは1時間ごとにバッチ処理されます。コードが本番環境で稼働した後、通常、次のバッチ処理が開始されてから15分以内に新しいメッセージが表示されます。［プロダクト］>［エージェントアナリティクス］アクセスし、エージェントを選択し、［会話］タブを開いて、訪問者のプロンプトとエージェントの回答の両方が表示されることを確認します。
注意:アプリケーションが API 呼び出しを再試行したり、イベントを再生したりする場合は、Pendo でレコードが重複しないように、必ず同じMessageIDを再利用してください。