TypeScript SDKをインストールして会話とトレースデータを送信する（ベータ）

Pendo TypeScript SDKを使用すると、TypeScriptベースのAIエージェントを導入し、Pendo Web SDKを必要とせずに、会話データやトレースデータをバックエンドから直接Pendoに送信できます。この記事では、OpenTelemetryまたはLangChain.jsを使用したインストール、初期化、トレースの有効化について説明します。

トレースの概念的な概要と、Pendo におけるトレースデータがどのように表示されるかについては、 「エージェントトレースの理解と確認」を参照してください。

前提条件

始める前に、以下のものを用意してください。

• Node.js 18以降。
• Pendoでエージェントの全会話が有効化されていること。設定手順については、「PendoでのAIエージェントの追加と設定」を参照してください。
• アプリの公開アプリID。サブスクリプション管理者は、該当するアプリを開いた後、［設定］>［サブスクリプション設定］>［アプリケーション］でこの情報を見つけることができます。
• あなたのエージェントID。これを見つけるには、［プロダクト］>［エージェントアナリティクス］に移動し、エージェント名の横にある設定アイコンを選択します。

SDKをインストールする

Pendo TypeScript SDKをインストールするには、以下を実行します。

npm install pendo-server-sdk

SDKの初期化

起動時に、エージェントがリクエストを処理する前に、init()を1回呼び出します。公開アプリIDとデフォルトの訪問者IDおよびアカウントIDを渡して、各リクエストのコンテキストを更新します。

import { init, setContext } from 'pendo-server-sdk';

// アプリ起動時に初期化 startup  
init({
    apiKey: process.env.PENDO_SDK_API_KEY,
    agentId: 'my-agent',
  });
  
  // リクエストに応じてこの呼び出しツリーの初期化時の識別子を上書き
  await setContext(
    { visitorId: user.email, accountId: user.orgId, conversationId: threadId },
    async () => agent.invoke({ input: message }),
  );

トレースデータを取得する

TypeScript SDKは、OpenTelemetry（OTel）とLangChain.jsの両方を通じて、会話データとトレースデータをキャプチャできます。

OpenTelemetryでトレースを設定する

OpenTelemetryでトレースを設定するには、Node.js環境にOTelがインストールされている必要があります。

OTelが稼働している場合、Pendo SDKは追加のSDK設定なしでトレースデータを自動的に取得します。

LangChain.jsでトレースを設定する

LangChain.jsでトレースを設定するには、Node.js環境にインストールされている必要があります。

PendoCallbackHandlerをLangChainの設定に追加してください。ハンドラーはエージェントの実行中に、各プロンプト、レスポンス、ツール呼び出し、LLM呼び出し、実行ステップを自動的にキャプチャします。追加の追跡呼び出しは必要ありません。

import { PendoCallbackHandler } from 'pendo-server-sdk/langchain_callback';

const handler = new PendoCallbackHandler();
const result = await llm.invoke(prompt, { callbacks: [handler] });

設定を確認する

SDKをセットアップしたら、開発環境またはステージング環境でエージェントを実行し、テストプロンプトを送信してください。次に、データがPendoに届いていることを確認します。

• エージェントアナリティクスを確認します。会話データは1時間ごとにバッチ処理されます。コードが本番環境で稼働した後、通常、次のバッチ処理が開始されてから15分以内に新しいメッセージが表示されます。［プロダクト］>［エージェントアナリティクス」に移動し、エージェントを選択して、［会話］タブを開き、プロンプトと応答が表示されていることを確認します。
• トレースデータを確認します。トレースデータを含む会話では、会話ビューで関連するプロンプトや応答の横にアクティビティアイコンが表示されます。それを選択すると［会話トレース］ビューが開きます。詳細については、「エージェントトレースの理解と確認」を参照してください。

ヒント：アプリケーションがAPI呼び出しを再試行したり、イベントを再生したりする場合は、Pendoで重複レコードが発生しないように同じmessageId再利用してください。

ユーザーのリアクションを手動で記録する

TypeScript SDKは、選択した設定オプションを使用して、プロンプト、応答、トレースデータを自動的にキャプチャします。

また、サムズアップやサムズダウンのフィードバックなどのuser_reactionイベントも記録したい場合は、recordReactionを使って手動で送信する必要があります。

import { recordReaction } from "pendo-server-sdk";
  
  recordReaction({
    conversationId,
    reactionType,        // 'thumbs_up', 'thumbs_down', or 'unreact'
    messageId,           // same id as the message this reaction is tied to
    feedbackComment,     // optional free-text string
    visitorId,
    accountId,
  });

トラブルシューティング

Pendoにデータが表示されない場合は、以下の項目を順番に確認してください。