エージェント分析のインストルメンテーションを確認する
実インタラクションを1回送信し、ライブイベントで生成されるイベントで9つのゲートをチェックすることで、インストルメンテーションを検証します。 ゲートは、イベントが到着したことを確認し、モデル、トークン、コスト、レイテンシのデータを伝送し、実際のセッション、エージェント、ユーザーIDを使用し、プライバシーモードで送信されたときにメッセージのコンテンツが含まれます。 任意のパスを使用してインストルメントを実行した後、このチェックを本番チェックリストを使用してロールアウトする前に再度実行してください。
9つのゲートを確認する
インストルメント化されたコードから1つの実際のインタラクションを送信し、プロジェクトのライブイベントストリームを開き、次のことを確認します。
- イベントがそもそも到着しているか。
- モデル名とプロバイダーが入力されているか。
- トークン数が入力されます。
- Cost USDが入力されます。
- Latencyが入力されています。
- セッションIDが自動生成されたプレースホルダではなく、実際のIDになっているか。
- エージェントIDがコンポーネントごとに設定されているか。
- ユーザーIDは認証レイヤーから取得されます。
- メッセージのコンテンツは、プライバシーモードでコンテンツを送信するときに、ユーザーメッセージに存在します。
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を使用している場合は、ドクターを実行して、環境変数、インストール済みの依存関係、イベントとパイプラインの接続を検証します。
npx -y -p @amplitude/ai amplitude-ai doctor
ドクターはデフォルトでAMPLITUDE_AI_API_KEYを読み取ります。アプリでキーに別の名前を付ける場合は、-key-envを使用してdoctorに正しい変数を指定してください:
npx -y -p @amplitude/ai amplitude-ai doctor -key-env MY_KEY_NAME
値を入力せずに-key-envを渡した場合、ドクターはデフォルトにフォールバックするのではなく、使用方法のメッセージを表示して終了します。
summary()でフィルレートレポートを取得する
導入前に、MockAmplitudeAI.summary() を使用して、キャプチャされたすべてのイベントのフィルレートレポートを取得します。データがAmplitudeに到達する前に、検証ゲートをチェックし、ギャップにフラグを立てます。
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());
サマリー出力は次のようになります。
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リファレンスのモッククライアントに対するテストを参照してください。
失敗するゲートを修正する
| ゲート障害 | 原因 | 修正 |
|---|---|---|
user_id 欠落 | セッションに渡された userIdまたは deviceIdはありません | Browser SDKを使用して、agent.session()でuserIdを設定するか、deviceIdを転送します |
Session ID 欠落 | ID なしでセッションが作成されました | sessionIdをagent.session()に渡す |
Model / Provider | サポートされているプロバイダーを使用しない、またはカスタムゲートウェイを使用するpatch() | モデルとプロバイダーを明示的に trackAiMessage() に渡すか、プロバイダー ラッパーを使用してください |
Input/Output Tokens = 0 | プロバイダーはストリーミングモードでの使用状況を返しません | onFinish / stream_options: { include_usage: true } を使用して最終的なトークン数をキャプチャする |
Cost USD = 0 | 認識できないモデル名 | 正規のプロバイダーモデルIDを使用するか、明示的にtotalCostUsdを設定してください。 |
その他の症状については、エージェント分析の設定に関するトラブルシューティングを参照してください。
プロダクションチェックリスト
イベントが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.