エージェント分析エクスポートAPI
エクスポートAPIを使用して、本番エージェントのセッション、キュレーションされたデータセット、評価ツールの設定を独自のオフライン評価パイプラインにプルします。
エクスポートAPIは、本番エージェントのデータをJSONとして返すため、独自のツールで評価を実行できます。APIは、セッション、Amplitudeでキュレーションしたデータセット、および定義した評価ツールの設定を対象としています。オフラインパイプラインは、プロダクトが使用するものと同じセッション、同じ判断基準、同じスコアを読み取ることができます。
このAPIは読み取り専用です。 データを送信するには、AI SDKを使用しないでエージェントイベントを送信するを参照してください。
これらのエンドポイントは、OpenAPI定義のDeveloper APIの一部ではないため、このリファレンスには表示されず、amp CLIもサポートしていません。HTTP経由で直接呼び出します。
認証とリクエストの要件
- すべてのエンドポイントはHTTP Basic認証を使用します。 ユーザー名としてプロジェクトのAPIキーを使用し、パスワードとしてシークレットキーを使用します。 APIキーとシークレットキーを見つけるを参照してください。
- 認証済みのプロジェクトが、どのデータを受け取るかを決定します。
project_idパラメータは存在せず、キーで別のプロジェクトのデータをリクエストすることはできません。 - ページネーションカーソルは不透明な文字列です。前のレスポンスからの
next_page_tokenを変更せずに渡します。 - 1回のトラバーサルのすべてのページで、
sort_orderとすべてのフィルターを同じ状態に保ちます。ページネーションはスナップショットではなくライブデータを読み取るため、トラバーサルの途中でデータが変更されると、それ以降のページの内容に影響が出ることがあります。
地域
プロジェクトをホストするデータセンターにリクエストを送信します。
| 地域 | ベースURL |
|---|---|
| 米国 | https://developer-api.amplitude.com |
| 欧州連合 | https://developer-api.eu.amplitude.com |
キーはリージョン間で相互に交換できません。 米国プロジェクトのキーは、EUホストに対して401を返します。
ルックバックとセッションの可視性
2つのプロダクトルールがレスポンスの内容を決定します。両方ともページ分割の前に適用されます。
- ルックバック期間:プランの資格設定により、利用可能なセッションの期間が制限されます。 そのウィンドウ外の時間範囲を明示的にリクエストすると、範囲が絞り込まれるのではなく、
400が返されます。ルックバックの権限がない組織は、セッションとデータセットのエンドポイントを使用できません。 開始する前に権限を割り当てます。 - セッション上限:セッション上限に達した組織は、新しいセッションをエクスポートできません。すでにエンリッチされたセッションは引き続き利用可能です。
Amplitudeは、セッションをサイレントにドロップするのではなく、除外されたセッションとして報告します。コレクションレスポンスには、フィルターが削除した内容と理由をカウントするomissions配列が含まれます。
この2つの収集エンドポイントは、保留されたセッションを除外し、omissionsセッションのカウントに含めます。単一セッションエンドポイントは代わりに403を返します。これは、省略すべきものがないからです。
| 理由 | 意味 |
|---|---|
session_not_found | データセットメンバーのセッションが存在しません。 |
outside_lookback_window | このセッションは、ルックバックの権限の対象外です。 |
session_cap | 組織はセッション上限に達したため、Amplitudeはセッションを保留します。 |
省略数は、現在のページではなく、一致するコレクション全体を表します。カウントはすべてのページで繰り返されるため、ページ間でカウントを追加しないでください。
セッションの一覧
認証済みプロジェクトのセッションをページネーション付きのリストで返します。メタデータと人によるレビューも含まれます。トレース、スパン、およびターンは、単一セッションエンドポイントから取得されます。
GET /v1/agent-analytics/export/sessions
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions' \
-u '{api_key}:{secret_key}'
エージェントおよび期間でフィルタ:
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions?agent_name=support-bot&start_time=2026-01-01T00%3A00%3A00Z&end_time=2026-01-31T23%3A59%3A59Z&page_size=100' \
-u '{api_key}:{secret_key}'
次のページを取得します:
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions?page_size=100&page_token={next_page_token}' \
-u '{api_key}:{secret_key}'
クエリパラメータ
| 名前 | 概要 |
|---|---|
user_id | オプションです。文字列です。 1つのユーザーIDに対するセッションを返します。 |
agent_name | オプションです。文字列です。 1つのエージェントのセッションを返します。 |
start_time | オプションです。タイムゾーンオフセット付きのISO 8601文字列。セッション開始時刻の下限値(この値を含む)。ルックバックウィンドウの外にある値は400を返します。 |
end_time | オプションです。タイムゾーンオフセット付きのISO 8601文字列。セッション開始時刻の上限値(この値を含みます)。開始時刻よりも前の終了時刻は400を返します。 |
page_size | オプションです。1~200の間の整数。デフォルトは50です。 |
page_token | オプションです。文字列です。 前のレスポンスnext_page_tokenからの不透明なカーソル。 |
sort_order | オプションです。文字列。descは最新のセッションから先に返します(デフォルト)。ascは最も古いセッションから先に返します。ページ全体でsort_orderを一貫させます。 |
レスポンス
{
"sessions": [
{
"session": {
"object": "agent_session",
"id": "string",
"project_id": "string",
"user_id": "string",
"agent_name": "string",
"start_time": "2026-01-15T10:00:00.000Z",
"end_time": "2026-01-15T10:04:12.000Z",
"duration_ms": 252000,
"num_traces": 3,
"num_errors": 0,
"models_used": ["string"],
"total_input_tokens": 2406,
"total_output_tokens": 225,
"total_cost_usd": 0.001285,
"status": "enriched",
"enrichment_status": "completed",
"last_message": "string",
"metadata": {}
},
"human_review": { "comments": [], "tags": [] }
}
],
"next_page_token": "string",
"omissions": [{ "reason": "session_cap", "count": 12 }]
}
| プロパティ | 概要 |
|---|---|
sessions[].session.id | セッション識別子。 単一のセッションをリクエストする場合は、この値を{session_id}として使用してください。 |
sessions[].session.duration_ms | ウォールクロック方式のセッションの期間(ミリ秒単位)。 |
sessions[].session.status | セッションのライフサイクル状態(例:closedまたはenriched)。 |
sessions[].session.enrichment_status | 品質シグナルエンリッチメントの状態(例:pendingまたはcompleted)。 |
sessions[].session.last_message | メッセージコンテンツが利用可能になった場合の、会話内の最後のメッセージ。 |
sessions[].human_review | Amplitudeでレビューアーが追加したコメントとタグ。 |
next_page_token | 次のページのカーソル。 最後のページにはありません。 |
omissions | フィルターが削除したセッションの数、理由別。 |
セッションを1つ取得する
完全なトレース、スパン、サニタイズされたターン、評価結果、エンリッチメント、およびデータセットのメンバーシップを含む1つのセッションを返します。
GET /v1/agent-analytics/export/sessions/{session_id}
セッションリストからidを使用します。 セッションIDは、インストルメンテーションが送信する識別子であり、Amplitudeの他の場所に表示される数値の行IDではありません。
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions/{session_id}' \
-u '{api_key}:{secret_key}'
レスポンス
{
"session": { "object": "agent_session" },
"traces": [
{
"object": "agent_trace",
"id": "string",
"spans": [
{
"object": "agent_span",
"id": "string",
"name": "llm_completion",
"attributes": {},
"raw_input": "string",
"raw_output": "string"
}
]
}
],
"turns": [
{
"object": "agent_turn",
"id": "string",
"trace_id": "string",
"turn_index": 1,
"role": "user",
"latency_ms": 0,
"created_at": "2026-01-15T10:00:00.000Z",
"provider_request_id": null
}
],
"evaluations": [
{
"object": "agent_evaluation",
"evaluator_id": "string",
"evaluator_type": "detector",
"granularity": "session",
"span_id": null,
"passed": null,
"status": "success",
"model_used": "string",
"cost_usd": 0.00146,
"latency_ms": 4427,
"created_at": "2026-01-15T10:00:00.000Z",
"result": {}
}
],
"enrichments": [{ "object": "agent_session_enrichment" }],
"datasets": [],
"human_review": { "comments": [], "tags": [] },
"conversation_turn_count": 4,
"shared_attributes": {}
}
| プロパティ | 概要 |
|---|---|
traces[].spans[].attributes | インストルメンテーションが送信したままのSpan属性。キーセットは、SDKとエージェントによって異なります。 |
traces[].spans[].raw_input | メッセージのコンテンツが利用可能な場合、スパンのテキストを入力します。 |
traces[].spans[].raw_output | メッセージのコンテンツが利用可能な場合、スパンのテキストを出力します。 |
turns | 順序付けられたターンレコード。メッセージコンテンツは、ターンではなく、スパンに存在します。 |
turns[].created_at | ターンのタイムスタンプ。 この値を基準にソートすることで、会話を正しい順序で再構築できます。 |
turns[].provider_request_id | 完了に対するモデルプロバイダー自身の識別子。 これを使用して、ターンを独自の推論レコードに結合します。nullこれは、ユーザーターン、およびインストルメンテーションでキャプチャされなかったアシスタントターンに使用します。プロバイダーのリクエストIDを参照してください。 |
evaluations | 定義した評価ツールからの結果。評価ツールごとに1つのエントリ。評価結果を参照してください。 |
enrichments | Amplitudeが計算した品質シグナル、トピック分類、ルーブリックスコア。 |
datasets | このセッションが属するデータセット。 |
conversation_turn_count | ユーザーとの対話のターン数。 |
shared_attributes | 重複排除済みのスパン属性。 共有属性を参照してください。 |
プロバイダーのリクエストID
turns[].provider_request_idには、モデルプロバイダーが生成に割り当てた識別子が含まれています。Amplitudeは、インストルメンテーションから送信されるgen_ai.response.id属性から読み取ります。これはAmplitudeのターンとプロバイダー側のリクエストレコードとの間の結合キーであり、評価スコアをプロバイダーに送信したり、請求額とコストを照合したりする際に使用すべきフィールドです。
この形式はプロバイダーの形式であり、Amplitudeの形式ではありません。chatcmpl-...などのプレフィックス付きの文字列を返すプロバイダーもいれば、プレフィックスなしのベアトークンを返すプロバイダーもいます。この値は不透明なものとして扱い、自身のレコードと照合するだけにして、解析したり形状を想定したりしないでください。
次の3つの場合にnullになります:完了を持たないユーザーのターン、属性をキャプチャしないインストルメンテーションによるアシスタントターン、そしてフィールドが存在する前にAmplitudeが取り込んだセッションの場合。バックフィルがないため、欠落IDはエラーではなくギャップとして扱います。
評価結果
evaluationsの各エントリは、このセッションに対する1人の評価者による最新の結果です。Amplitudeは、代わりに独自の組み込みシグナルをレポートenrichmentsします。
| プロパティ | 概要 |
|---|---|
evaluator_id | この結果を生成した評価者。 評価ツールの設定を取得するからその定義を取得します。 |
evaluator_type | 評価者の形状(例:detector、classifier、またはrubric)。 これは、どのキーresultを保持しているかを決定します。 |
granularity | 評価ツールが採点した対象です。セッション全体の場合はsessionとなり、スパンレベルの評価ツールではspan_idも設定されます。 |
passed | 結果が評価者の合格しきい値を満たしているかどうか、あるいは評価者にしきい値がない場合にどうなるかnullを示します。 |
status | 評価ツールが結果を生成した時点てsuccessになります。その他のステータスの場合、resultは空白になることがあり、result.errorにその理由が説明されます。 |
model_used, cost_usd, latency_ms | Amplitudeがこの評価器を実行するのにかかる費用。 モデルを呼び出さないルールベースの評価ツールの場合は存在しません。 |
result | 評価者の出力。そのキーはevaluator_typeに依存します。 |
resultはAmplitudeによって評価ツールの出力どおりにそのまま引き渡されるので、含まれるキーは一定ではありません。
| 評価ツールのタイプ | キー |
|---|---|
| Rubric | score, normalized_score |
| 分類子 | primary, secondary |
| 検出ツール | detected, signals |
ほとんどの結果には、結果を説明するrationaleと、それを裏付ける会話の該当部分を引用したevidenceも含まれます。
これらは、ブランチ調査する価値のあるキーであり、完全なリストではありません。 結果には、評価者自身の信頼度スコアや、その結果の読み取り数に関するカウントなど、他のものがあり、そのセットは評価者パイプラインによって変化します。 必要なキーを読み取り、残りは無視します。
resultは、evaluator_id、status、cost_usd、latency_msなどのいくつかのエンベロープフィールドも繰り返し含まれます。エンベロープ側のコピーを優先してください。Amplitudeはそれらをこのリファレンスに記載されている型に正規化しますが、result内の値は評価ツールが書き込んだままの状態であるため、精度が異なる場合があります。
分類子の値は、ブランチする列挙型ではなく、表示およびグループ化するためのラベルとして扱います。評価モデルがそれらを生成します。評価者が返すことができる値のセットは、そのモデルまたはそのプロンプトが変更されるにつれて変更される可能性があります。 パイプラインで固定された結果セットが必要な場合は、リストが閉じられたと想定するのではなく、関心のある値をマッピングし、認識できない値を処理します。
共有属性
システムプロンプトやツール定義など、スパン全体で繰り返し発生するスパン属性は、セッションレベルのshared_attributesマップに1回保存されます。それぞれの出現箇所には、値の代わりに参照が含まれます。
{ "$shared_attribute": "a1b2c3d4" }
shared_attributesでその値を検索することで、値の参照を解決します。重複排除はロスレスであり、レスポンスを数メガバイトから数百キロバイトに削減できます。何も繰り返しのないセッションでは、shared_attributesが空のオブジェクトとして返されます。
1つのレスポンスで返すには大きすぎるセッションは、部分的なデータを返すのではなく、400で失敗します。エクスポートがトレースやターンを暗黙的にトランケートすることはありません。
データセットを取得する
データセットと、そのメンバーセッションのページネーション付きリストを返します。これには正解ラベルと人によるレビューも含まれます。
GET /v1/agent-analytics/export/datasets/{dataset_id}
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/datasets/{dataset_id}?page_size=50' \
-u '{api_key}:{secret_key}'
クエリパラメータ
| 名前 | 概要 |
|---|---|
page_size | オプションです。1~200の間の整数。デフォルトは50です。 |
page_token | オプションです。文字列です。 前のレスポンスnext_page_tokenからの不透明なカーソル。 |
sort_order | オプションです。文字列。desc(デフォルト)またはasc、セッションがデータセットに追加された時刻の順序。 |
user_idやagent_nameなどのセッションフィルタはこのエンドポイントでは無効であり、400を返します。
レスポンス
{
"dataset": {
"object": "agent_dataset",
"id": "string",
"project_id": "string",
"name": "string",
"description": "string",
"agent_name": "string",
"source_type": "manual",
"created_at": "2026-01-15T10:00:00.000Z",
"updated_at": "2026-01-15T10:00:00.000Z"
},
"members": [
{
"object": "agent_dataset_member",
"session_id": "string",
"added_at": "2026-01-15T10:00:00.000Z",
"selection_reason": "string",
"ground_truth_labels": {
"evaluator_results": {},
"overridden_evaluators": [],
"review_status": "partial",
"reviewed_by": "string",
"reviewed_at": "2026-01-15T10:00:00.000Z"
},
"session": { "object": "agent_session" },
"human_review": { "comments": [], "tags": [] }
}
],
"next_page_token": "string",
"omissions": []
}
| プロパティ | 概要 |
|---|---|
members[].ground_truth_labels | このセッションの人間検証済みのラベル。は、評価者IDをその検証済みの判定にマップし、evaluator_resultsレビュー者が訂正した評価者をoverridden_evaluatorsリストします。 |
members[].ground_truth_labels.review_status | レビューの完了状況(例:partialまたはverifiedなど)。 |
members[].session | セッションメタデータ。セッションリストが返すものと同じ形状です。 |
各メンバーにはセッションメタデータのみが含まれます。そのトレースとターンについて、セッションを個別にリクエストします。
評価ツールの設定を取得する
1つの評価者設定(プロンプト、モデル、ラベルを含む)を返すため、独自のツールで同じ判定を再現できます。
GET /v1/agent-analytics/export/evaluators/{evaluator_id}
このエンドポイントはセッションデータを読み取らないため、ルックバックウィンドウとセッションキャップは適用されません。
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/evaluators/{evaluator_id}' \
-u '{api_key}:{secret_key}'
レスポンス
{
"config": {
"object": "agent_evaluator",
"id": "string",
"project_id": "string",
"topic": "string",
"status": "draft",
"output_type": "binary",
"run_on": "all",
"description": "string",
"tags": [{ "id": "yes", "label": "True", "description": "string", "examples": [] }],
"prompt": "string",
"model": "string",
"evaluation_method": "llm",
"granularity": "session",
"created_at": "2026-01-15T10:00:00.000Z",
"updated_at": "2026-01-15T10:00:00.000Z"
}
}
| プロパティ | 概要 |
|---|---|
config.topic | 評価者の表示名。 |
config.status | 評価者がdraftまたはアクティブかどうか。 |
config.output_type | 評決の形状(例:binaryまたはrubric)。 |
config.tags | 評価者が返すことができるラベル。説明と例が含まれます。 |
config.prompt | LLM評価者用の判断プロンプト。 |
config.model | LLM評価者が実行されるモデル。 |
config.evaluation_method | llm モデル判断型評価子の場合は、決定論型評価子の場合はcode。 |
ステータスとエラーコード
| コード | 概要 |
|---|---|
200 OK | リクエストに成功しました。 |
400 Bad Request | 無効なパラメータ、ルックバックウィンドウ外の時間範囲、反転された時間範囲、または大きすぎて返せないセッション。 |
401 Unauthorized | 認証情報の欠落もしくは無効、または別のリージョンのキー。 |
403 Forbidden | リクエストされたセッションは、セッション上限により制限されています。シングルセッションエンドポイントのみがこのコードを返します。 |
404 Not Found | 認証済みのプロジェクトには、その ID を持つセッション、データセット、またはエバリュエーターは存在しません。 |
429 Too Many Requests | レート制限を超えましたRetry-Afterヘッダー内の間隔の後で を再試行します。 |
503 Service Unavailable | 一時的Retry-Afterヘッダー内の間隔の後で を再試行します。 |
エapplication/problem+jsonラーには、フィerror_codeールドおよびフラretryableグが含まれます。
これは役に立ちましたか?
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.