エージェント分析エクスポート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とすべてのフィルターを同じ状態に保ちます。ページネーションはスナップショットではなくライブデータを読み取るため、トラバーサルの途中でデータが変更されると、それ以降のページの内容に影響が出ることがあります。

地域

プロジェクトをホストするデータセンターにリクエストを送信します。

キーはリージョン間で相互に交換できません。 米国プロジェクトのキーは、EUホストに対して401を返します。

ルックバックとセッションの可視性

2つのプロダクトルールがレスポンスの内容を決定します。両方ともページ分割の前に適用されます。

  • ルックバック期間:プランの資格設定により、利用可能なセッションの期間が制限されます。 そのウィンドウ外の時間範囲を明示的にリクエストすると、範囲が絞り込まれるのではなく、400が返されます。ルックバックの権限がない組織は、セッションとデータセットのエンドポイントを使用できません。 開始する前に権限を割り当てます。
  • セッション上限:セッション上限に達した組織は、新しいセッションをエクスポートできません。すでにエンリッチされたセッションは引き続き利用可能です。

Amplitudeは、セッションをサイレントにドロップするのではなく、除外されたセッションとして報告します。コレクションレスポンスには、フィルターが削除した内容と理由をカウントするomissions配列が含まれます。

この2つの収集エンドポイントは、保留されたセッションを除外し、omissionsセッションのカウントに含めます。単一セッションエンドポイントは代わりに403を返します。これは、省略すべきものがないからです。

省略数は、現在のページではなく、一致するコレクション全体を表します。カウントはすべてのページで繰り返されるため、ページ間でカウントを追加しないでください。

セッションの一覧

認証済みプロジェクトのセッションをページネーション付きのリストで返します。メタデータと人によるレビューも含まれます。トレース、スパン、およびターンは、単一セッションエンドポイントから取得されます。

GET /v1/agent-analytics/export/sessions

bash
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions' \
-u '{api_key}:{secret_key}'

エージェントおよび期間でフィルタ:

bash
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}'

次のページを取得します:

bash
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions?page_size=100&page_token={next_page_token}' \
-u '{api_key}:{secret_key}'

クエリパラメータ

レスポンス

json
{
  "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 }]
}

セッションを1つ取得する

完全なトレース、スパン、サニタイズされたターン、評価結果、エンリッチメント、およびデータセットのメンバーシップを含む1つのセッションを返します。

GET /v1/agent-analytics/export/sessions/{session_id}

セッションリストからidを使用します。 セッションIDは、インストルメンテーションが送信する識別子であり、Amplitudeの他の場所に表示される数値の行IDではありません。

bash
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/sessions/{session_id}' \
-u '{api_key}:{secret_key}'

レスポンス

json
{
  "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": {}
}

プロバイダーのリクエストID

turns[].provider_request_idには、モデルプロバイダーが生成に割り当てた識別子が含まれています。Amplitudeは、インストルメンテーションから送信されるgen_ai.response.id属性から読み取ります。これはAmplitudeのターンとプロバイダー側のリクエストレコードとの間の結合キーであり、評価スコアをプロバイダーに送信したり、請求額とコストを照合したりする際に使用すべきフィールドです。

この形式はプロバイダーの形式であり、Amplitudeの形式ではありません。chatcmpl-...などのプレフィックス付きの文字列を返すプロバイダーもいれば、プレフィックスなしのベアトークンを返すプロバイダーもいます。この値は不透明なものとして扱い、自身のレコードと照合するだけにして、解析したり形状を想定したりしないでください。

次の3つの場合にnullになります:完了を持たないユーザーのターン、属性をキャプチャしないインストルメンテーションによるアシスタントターン、そしてフィールドが存在する前にAmplitudeが取り込んだセッションの場合。バックフィルがないため、欠落IDはエラーではなくギャップとして扱います。

評価結果

evaluationsの各エントリは、このセッションに対する1人の評価者による最新の結果です。Amplitudeは、代わりに独自の組み込みシグナルをレポートenrichmentsします。

resultはAmplitudeによって評価ツールの出力どおりにそのまま引き渡されるので、含まれるキーは一定ではありません。

ほとんどの結果には、結果を説明するrationaleと、それを裏付ける会話の該当部分を引用したevidenceも含まれます。

これらは、ブランチ調査する価値のあるキーであり、完全なリストではありません。 結果には、評価者自身の信頼度スコアや、その結果の読み取り数に関するカウントなど、他のものがあり、そのセットは評価者パイプラインによって変化します。 必要なキーを読み取り、残りは無視します。

resultは、evaluator_id、status、cost_usd、latency_msなどのいくつかのエンベロープフィールドも繰り返し含まれます。エンベロープ側のコピーを優先してください。Amplitudeはそれらをこのリファレンスに記載されている型に正規化しますが、result内の値は評価ツールが書き込んだままの状態であるため、精度が異なる場合があります。

分類子の値は、ブランチする列挙型ではなく、表示およびグループ化するためのラベルとして扱います。評価モデルがそれらを生成します。評価者が返すことができる値のセットは、そのモデルまたはそのプロンプトが変更されるにつれて変更される可能性があります。 パイプラインで固定された結果セットが必要な場合は、リストが閉じられたと想定するのではなく、関心のある値をマッピングし、認識できない値を処理します。

共有属性

システムプロンプトやツール定義など、スパン全体で繰り返し発生するスパン属性は、セッションレベルのshared_attributesマップに1回保存されます。それぞれの出現箇所には、値の代わりに参照が含まれます。

json
{ "$shared_attribute": "a1b2c3d4" }

shared_attributesでその値を検索することで、値の参照を解決します。重複排除はロスレスであり、レスポンスを数メガバイトから数百キロバイトに削減できます。何も繰り返しのないセッションでは、shared_attributesが空のオブジェクトとして返されます。

1つのレスポンスで返すには大きすぎるセッションは、部分的なデータを返すのではなく、400で失敗します。エクスポートがトレースやターンを暗黙的にトランケートすることはありません。

データセットを取得する

データセットと、そのメンバーセッションのページネーション付きリストを返します。これには正解ラベルと人によるレビューも含まれます。

GET /v1/agent-analytics/export/datasets/{dataset_id}

bash
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/datasets/{dataset_id}?page_size=50' \
-u '{api_key}:{secret_key}'

クエリパラメータ

user_idやagent_nameなどのセッションフィルタはこのエンドポイントでは無効であり、400を返します。

レスポンス

json
{
  "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": []
}

各メンバーにはセッションメタデータのみが含まれます。そのトレースとターンについて、セッションを個別にリクエストします。

評価ツールの設定を取得する

1つの評価者設定(プロンプト、モデル、ラベルを含む)を返すため、独自のツールで同じ判定を再現できます。

GET /v1/agent-analytics/export/evaluators/{evaluator_id}

このエンドポイントはセッションデータを読み取らないため、ルックバックウィンドウとセッションキャップは適用されません。

bash
curl 'https://developer-api.amplitude.com/v1/agent-analytics/export/evaluators/{evaluator_id}' \
-u '{api_key}:{secret_key}'

レスポンス

json
{
  "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"
  }
}

ステータスとエラーコード

エ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.

このページでは