エージェント分析のインストルメンテーションを確認する

実インタラクションを1回送信し、ライブイベントで生成されるイベントで9つのゲートをチェックすることで、インストルメンテーションを検証します。 ゲートは、イベントが到着したことを確認し、モデル、トークン、コスト、レイテンシのデータを伝送し、実際のセッション、エージェント、ユーザーIDを使用し、プライバシーモードで送信されたときにメッセージのコンテンツが含まれます。 任意のパスを使用してインストルメントを実行した後、このチェックを本番チェックリストを使用してロールアウトする前に再度実行してください。

9つのゲートを確認する

インストルメント化されたコードから1つの実際のインタラクションを送信し、プロジェクトのライブイベントストリームを開き、次のことを確認します。

  1. イベントがそもそも到着しているか。
  2. モデル名とプロバイダーが入力されているか。
  3. トークン数が入力されます。
  4. Cost USDが入力されます。
  5. Latencyが入力されています。
  6. セッションIDが自動生成されたプレースホルダではなく、実際のIDになっているか。
  7. エージェントIDがコンポーネントごとに設定されているか。
  8. ユーザーIDは認証レイヤーから取得されます。
  9. メッセージのコンテンツは、プライバシーモードでコンテンツを送信するときに、ユーザーメッセージに存在します。

AIコーディングエージェントを使用してインストルメンテーションした場合は、インストルメンテーションの一環として検証テストを記述します。 Gates 6 から 8 までの設定は意図的にプレースホルダ ID に対して失敗しているため、ロールアウト前にプレースホルダを実際の ID に置き換えてください。

Gate 9は、他のすべての場所で静かに失敗するものです。SDKは空のメッセージ文字列を送信する代わりに破棄するため、まだ入力されていない変数に接続されたエージェントはゲート1〜8をクリアしても、読み取るデータを何も提供しません。スレッドビューは空のままとなり、Amplitudeはコンテンツベースのシグナルをスコアリングできません。このゲートは、意図的にコンテンツを削除するmetadata_onlyまたはcustomer_enrichedには適用されません。

OpenTelemetryの場合、キーチェックはゲート6~8です。OpenTelemetryページのVerifyを参照してください。

デプロイする前にAI SDKを確認してください。

AI SDKを使用している場合は、ドクターを実行して、環境変数、インストール済みの依存関係、イベントとパイプラインの接続を検証します。

bash
npx -y -p @amplitude/ai amplitude-ai doctor

ドクターはデフォルトでAMPLITUDE_AI_API_KEYを読み取ります。アプリでキーに別の名前を付ける場合は、-key-envを使用してdoctorに正しい変数を指定してください:

bash
npx -y -p @amplitude/ai amplitude-ai doctor -key-env MY_KEY_NAME

値を入力せずに-key-envを渡した場合、ドクターはデフォルトにフォールバックするのではなく、使用方法のメッセージを表示して終了します。

summary()でフィルレートレポートを取得する

導入前に、MockAmplitudeAI.summary() を使用して、キャプチャされたすべてのイベントのフィルレートレポートを取得します。データがAmplitudeに到達する前に、検証ゲートをチェックし、ギャップにフラグを立てます。

typescript
import { AIConfig } from "@amplitude/ai";
import { MockAmplitudeAI } from "@amplitude/ai/testing";
const mock = new MockAmplitudeAI(new AIConfig({ contentMode: "full" }));
const agent = mock.agent("test-agent", { userId: "u1" });
await agent.session({ sessionId: "s1" }).run(async (s) => {
  s.trackUserMessage("hello");
  s.trackAiMessage("response", "gpt-4o-mini", "openai", 150);
});
console.log(mock.summary());

サマリー出力は次のようになります。

text
Agent Analytics fill-rate report
================================
Events captured: 2
  [Agent] User Message:  1
  [Agent] AI Response:   1
Verification gates (8/8 passing):
  ✓ user_id or device_id present
  ✓ [Agent] Session ID present
  ✓ [Agent] Agent ID present
  ✓ [Agent] Model Name present
  ✓ [Agent] Provider present
  ✓ [Agent] Latency Ms > 0
  ✓ [Agent] Input Tokens > 0
  ✓ [Agent] Output Tokens > 0
  ✓ [Agent] Cost USD > 0

これらのチェックをCIに保持するには、モッククライアントを使用してイベントにアサートします。 SDKリファレンスのモッククライアントに対するテストを参照してください。

失敗するゲートを修正する

その他の症状については、エージェント分析の設定に関するトラブルシューティングを参照してください。

プロダクションチェックリスト

イベントがAmplitudeに流れ始めたら、次のことを確認してください。

  • イベントには実際のユーザーIDが記録されます。
  • イベントには実際のセッションIDが格納されます。
  • セッションは結果が判明している場合に明示的に閉じられ、予期される場合にのみアイドルタイムアウトによって閉じられます。
  • プライバシーモードを決定し、確認しました。
  • エージェント ID は安定しており、人間が読み取れる形式になっています。また、委任用に子エージェントが設定されています。

これは役に立ちましたか?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

このページでは