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

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

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

前提条件

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

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

SDKをインストールする

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

pip install pendo-server-sdk

SDKの初期化

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

import pendo_sdk

# アプリ起動時に初期化
pendo_sdk.init(
api_key="your-pendo-app-id",
agent_id="your-agent-id",
endpoint="https://app.pendo.io/",
)

# 訪問者、アカウント、会話が変更されたらコンテキストを更新
pendo_sdk.set_context(
visitor_id="user@company.com",
account_id="acme_corp",
conversation_id="conversation_123456",
)

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

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

OpenTelemetryでトレースを設定する

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

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

LangChainでトレースを設定する

LangChainを使用してトレースをセットアップするには、Python環境にLangChainがインストールされている必要があります。

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

from pendo_sdk.langchain_callback import PendoCallbackHandler

handler = PendoCallbackHandler()
result = llm.invoke(prompt, config={"callbacks": [handler]})

設定を確認する

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

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

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

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

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

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

# 特定のメッセージに対するユーザーの反応を記録
pendo_sdk.record_reaction(
    conversation_id=conversation_id,
    reaction_type=reaction_type, # 'thumbs_up', 'thumbs_down', or 'unreact'
    message_span_id=message_id,# same id as the message this reaction is tied to
    feedback_comment=feedback_comment, # オプションのテキストフィードバックの配列
    visitor_id=visitor_id,
    account_id=account_id,
)

トラブルシューティング

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