Agent Analyticsの実験バリアントの記録

experimentsオプションは、エージェントが実行されたA/Bテストまたは機能フラグのバリアントを記録します。フラグクライアントがすでに返している割り当てを渡し、セッション内のすべての[Agent]イベントに[Agent] Experimentsを含め、単一の実験の場合は[Agent] Experiment Variantを渡します。任意のチャートをそのプロパティでグループ化し、プロンプト、モデル、ルーター、またはツールテストの各アーム全体で品質、コスト、または放棄状況を比較します。

エージェントの動作を変更するバリアントにはexperimentsを使用します。UIサーフェスなどの他のセグメント化ディメンションには[Agent] Contextを使用し、ランダム化されていないリリースにはagentVersion(Node)またはagent_version(Python)を使用します。

experimentsオプションには、0.24.1以降のNode @amplitude/aiリリースまたは1.20.1以降のPython amplitude-aiリリースが必要です。Amplitudeはバリアントを割り当てません。Amplitude 実験、Statsig、LaunchDarklyなどの既存のフラグまたは実験SDKを保持し、その結果を渡してください。

AI SDKを使用して割り当てを渡します。

エージェント、セッション、または単一のトラッキング呼び出しをexperimentsに設定します。各エントリはkeyとvariantを受け取り、さらにオプションとしてprovider(フラグシステムの名前)とunitを受け取ります。

typescript
const variant = await flags.getVariant('planner'); // your existing flag client
const agent = ai.agent('support-bot', { userId });
await agent
  .session({ sessionId, experiments: [{ key: 'planner', variant, provider: 'statsig' }] })
  .run(async (s) => {
    // Provider wrappers, tools, and tracking calls in the session all carry the experiment.
  });

SDKは、この順序でエントリを適用します。

  • エージェント。 エージェントのすべてのセッションに適用されます。子エージェントは親の実験を継承し、エントリを追加または上書きできます。
  • セッション。 同じキーを持つエージェントのエントリを上書きします。
  • **呼び出し。**エージェントまたはセッション追跡の呼び出しを1回行うと、そのイベントに限り、両方が上書きされます。

上書きによって、そのプロバイダーと単位を含むエントリ全体が置き換えられます。エントリは、そのキーが最初に出現した位置を保持します。

各イベントのプロパティ

実験が2つ以上の場合、イベントには配列のみが含まれます。すべてのプライバシーモードはこれらのプロパティを送信します。

単位を選択してください

unitはフラグクライアントがランダム化した内容を記録するため、分析では同等のもの同士を比較します。

  • agent_session(デフォルト)。セッションごとに1つの割り当て(例:会話の開始時に選択されたプロンプトやモデルなど)。
  • turn。ユーザーメッセージごとに新しい割り当て。例:各ターンで評価されるルーターなど。
  • span。ツールや取得戦略など、ターン内の操作ごとの新しい割り当て。OpenTelemetry評価のデフォルトはspanです。

検証と制限

SDK、OpenTelemetryレシーバー、およびウェアハウスインポートテンプレートにも同じルールが適用されます。 無効な入力によってエラーが発生することはありません。

  • key、variant、およびproviderは、ASCIIホワイトスペースをトリミングした後の1~256文字です。
  • keyに:を含めることはできません。variantには含められます(例:openai:gpt-4o)。
  • Amplitudeは、有効なキーまたはバリアントのないエントリをドロップします。 SDKは、ドロップされた各エントリをデバッグレベルで記録します。
  • 不明な値unitはデフォルト値にフォールバックされ、無効な値providerは除外されます。
  • 1つのイベントには、最大10個の実験が適用されます。これは、エージェント、セッション、および呼び出しのエントリがマージされた後にカウントされます。

キー、バリアント、およびプロバイダーはマスクされません。ユーザーデータは使用しないで、フラグとバリアント名を使用してください。

OpenTelemetryから割り当てを送信する

Agent Analyticsは、GenAIスパンからOpenTelemetry機能フラグの評価を読み取ります。 各feature_flag.evaluationスパンイベント、およびスパン自身のfeature_flag.*属性は、スパンが生成するすべてのイベントで1つの実験になります。属性名については、OTLPリファレンスの機能フラグ属性を参照してください。

HTTP APIまたはウェアハウスインポートから割り当てを送信する

自身で送信するイベントには、同じ5つのプロパティが含まれます。[Agent] Experimentsをkey:variant文字列の配列として設定します。単一実験プロパティは、1つの実験が適用される場合にのみ設定します。AI SDKなしでエージェントイベントを送信するを参照してください。

ウェアハウスインポートテンプレートは、オプションのexperiment_keyおよびexperiment_variant列を読み取ります。1行あたり1つの実験で、単位はagent_sessionです。データウェアハウスからエージェントの会話をインポートするを参照してください。

チャートをバリアントごとに分割する

  1. セッションのコストや放棄など、[Agent]イベントに基づいて構築された任意のチャートを開きます。
  2. [Agent] Experiment Variantにグループ化を追加します。複数の実験を含むセッションの場合は、代わりに[Agent] Experimentsでグループ化します。配列の各値は独自のグループになります。
  3. [Agent] Experiment Keyでフィルタリングして、1つのテストをビューに残します。

[Agent] Contextから移行する

以前のガイダンスでは、バリアントはcontextに含まれていました(例:context: { experiment_variant: 'treatment' })。これらの値は引き続き[Agent] Contextフィルタで機能します。新しいコードでは、割り当てをexperimentsとして渡し、contextから削除してください。これにより、各イベントは割り当てを一度だけ記録し、チャートでは専用のプロパティでグループ化できるようになります。

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

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.

このページでは