会話イベントを検証する

最終更新日: 2026年07月30日 00:18

イベントバリデーターは、AIエージェントの会話イベントペイロードを送信する前に、Pendoの要件と照らし合わせてチェックします。これにより、イベントが破棄または拒否される原因となるフォーマット上の問題を検出できます。これは、エージェントアナリティクスのAIエージェント設定ページにある開発者ツールです。

ブラウザSDKまたはサーバーAPIのいずれについてもペイロードを検証でき、イベント全体、そのプロパティのみ、またはJZBエンコードされたペイロードを貼り付けることができます。バリデーターはペイロードをプレビューするだけで、イベントを送信したり、Pendo内のデータを変更したりすることはありません。

ユースケース

次の目的でイベントバリデーターを使用します。

AIエージェントを計測する前に、ペイロードがPendoの要件に合っていることを確認し、ライブ配信後にイベントが失われないようにします。
サンプルペイロードを検証することで、エージェントアナリティクスに想定される会話イベントが表示されない理由を調査します。
agentModelUsedやagentFilesUploadedなどの非推奨フィールドから現在の代替フィールドに移行した後、ペイロードを確認します。

可用性

イベントバリデーターは、会話機能が有効になっているAIエージェントで利用可能です。これはエージェントの設定ページの［イベントバリデーター］セクションに表示され、そのエージェントの設定を開くことができるユーザーであれば誰でも使用できます。

会話を有効にする方法については、「クライアント側またはサーバー側のAPIを使用して会話イベントを送信する」をご覧ください。

イベントを検証する

会話イベントのペイロードを検証して、Pendoが受け入れるかどうかを確認します。

［プロダクト］>［エージェントアナリティクス］へ移動してください。
AIエージェント一覧から、確認したいエージェントの横にある歯車アイコンを選択して、設定ページを開きます。または、エージェントの詳細ページまたはレポートを開き、右上隅の ［アクション］>［設定を編集］を選択します。
［イベントバリデーター］セクションに移動してください。
イベントの送信方法に一致するソース（ブラウザSDKまたはサーバーAPI）を選択してください。
入力形式をイベント全体、プロパティのみ、JZBから選択してください。
ペイロードをボックスに貼り付けてください。例から始めるには、テンプレート（prompt、agent_response、user_reaction）を選択してください。
［イベントを検証］を選択します。
各フィールドの結果を確認し、問題を修正してから再度検証してください。

検証結果を読む

バリデーターは各フィールドおよびイベント全体のステータスを返します。

パス。このフィールドはすべての要件を満たしています。
警告。このフィールドには対処すべき問題があります。例えば、非推奨のフィールドが含まれているか、選択したエージェントやアプリと一致しない値が含まれている可能性があります。このイベントは一般的に依然として受け入れられます。
失敗。フィールドに重大なエラーがあります。例えば、必須フィールドが欠落している、またはデータ型が間違っているなどです。そのイベントは拒否され、取り込まれません。
情報。フィールドに関する追加情報。

失敗結果のないペイロードはPendoによって受け入れられます。

フォーマット要件

検証前に以下の一般的な要件を確認してください。

toolsUsedは["View"]などの文字列の配列でなければならず、"View"のような単純な文字列であってはなりません。単純な文字列はデコード中にイベント全体が破棄されます。
messageIdは数字ではなく文字列でなければなりません。123ではなく、"msg_001"を送信してください。
browser_timeは、エポックからのミリ秒単位の整数でなければなりません。小数点や秒単位は使用できません。
イベントは過去7日以内のものに限ります。30分以上先の日付のイベントはフラグが付けられます。
suggestedPromptは文字列ではなくブール値（true または false）でなければなりません。廃止予定のfileUploadedフィールドにも同じことが当てはまりますが、代わりにagentFilesUploadedフィールドを使用する必要があります。
user_reactionイベントの場合、contentはpositive、negative、またはunreact でなければなりません。自由記述式のフィードバックはagentUserReactionCommentsに入力してください。

フィールドリファレンス

以下の表は、バリデーターがチェックするすべてのフィールドを、必須、任意、Pendoによって設定、または非推奨のいずれであるかごとに分類して一覧表示しています。

必須のイベントフィールド

これらの最上位フィールドはすべてのイベントで必須です。

フィールド	タイプ	備考
`タイプ`	string	`prompt`、`agent_response`、または`user_reaction`のいずれか。
`browser_time`	integer	エポックからのミリ秒。過去7日以内、かつ30分以内の日付である必要があります。
`visitor_id`	string	空でない訪問者識別子。

必須のメッセージフィールド

propsオブジェクトは必須であり、これらの必須フィールドを含みます。

フィールド	タイプ	備考
`props.agentId`	string	Pendoで設定されたAIエージェントと一致している必要があります。
`props.conversationId`	string	会話型エージェントに必須で、空であってはなりません。
`props.messageId`	string	空でない文字列。数値であってはなりません。
`props.content`	string	メッセージの内容。`user_reaction`イベントの場合、`positive`、`negative`、または`unreact`でなければなりません。

任意のフィールド

これらのフィールドは任意です。

フィールド	タイプ	備考
`account_id`	string	アカウント識別子。
`url`	string	ページのURL。指定されていない場合はデフォルトで`http:///`になります。
`props.toolsUsed`	文字列の配列	文字列の配列である必要があります。空の文字列の場合、イベントは破棄されます。
`props.suggestedPrompt`	boolean	そのプロンプトが自動で提案されたかどうか。
`props.agentModelUsed`	文字列の配列	`modelUsed`よりも優先します。複数のモデルをサポートします。
`props.agentFilesUploaded`	オブジェクトの配列	`fileUploaded`よりも優先されます。各項目には名前とファイルタイプ（`csv`など）が必要です。
`props.agentSubagentsUsed`	文字列の配列	呼び出されたサブエージェントの名前。
`props.agentUserReaction` `Comments`	配列	`user_reaction`に付随する記述コメント。
`props.agentInputTokenCount`	integer	応答を生成するために使われるLLM入力トークン。トレースイベントのみ利用可能です。
`props.agentOutputTokenCount`	integer	応答の生成に使用されるLLM出力トークン。トレースイベントのみ利用可能です。

Pendoによって設定されたフィールド

Pendoはこれらのフィールドを自動的に入力します。手動で設定しないでください。

フィールド	タイプ	備考
`sessionId`	string	アナリティクスセッションID。
`tabId`	string	ブラウザタブ識別子。
`recordingId`	string	セッション記録ID。
`app_id`	文字列または数値	アプリケーションID。現在使用しているアプリが存在する場合は、それに対して検証を行います。
`subscription_id`	文字列または数値	サブスクリプションID。

非推奨およびレガシーのフィールド

これらのフィールドはまだ機能しますが、段階的に廃止されています。代わりに現行のフィールドを使用してください。

フィールド	タイプ	備考
`props.modelUsed`	string	非推奨。`agentModelUsed`を使用します。
`props.fileUploaded`	boolean	非推奨。`agentFilesUploaded`を使用します。
`props.prompt`	string	レガシー。`content`を使用してください。`prompt`と`content`両方を設定した場合、`prompt`が優先されます。