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を受け取ります。
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回行うと、そのイベントに限り、両方が上書きされます。
上書きによって、そのプロバイダーと単位を含むエントリ全体が置き換えられます。エントリは、そのキーが最初に出現した位置を保持します。
各イベントのプロパティ
| プロパティ | タイプ | 設定されている場合 |
|---|---|---|
[Agent] Experiments | 文字列の配列 | 少なくとも1つの有効な実験を持つすべてのイベント。 各値はkey:variantです(例:planner:v2)。 |
[Agent] Experiment Key | 文字列 | 正確に1つの実験が適用されます。 |
[Agent] Experiment Variant | 文字列 | 正確に1つの実験が適用されます。 |
[Agent] Experiment Unit | 文字列 | 正確に1つの実験が適用されます:agent_session、turn、またはspan。 |
[Agent] Experiment Provider | 文字列 | 正確に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です。データウェアハウスからエージェントの会話をインポートするを参照してください。
チャートをバリアントごとに分割する
- セッションのコストや放棄など、
[Agent]イベントに基づいて構築された任意のチャートを開きます。 [Agent] Experiment Variantにグループ化を追加します。複数の実験を含むセッションの場合は、代わりに[Agent] Experimentsでグループ化します。配列の各値は独自のグループになります。[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.