Agent 분석 내보내기 API

내보내기 API를 사용하여 프로덕션 에이전트 세션, 큐레이션된 데이터 세트 및 평가자 구성을 자체적인 오프라인 평가 파이프라인으로 가져옵니다.

내보내기 API는 프로덕션 에이전트 데이터를 JSON으로 반환하므로 자체 툴링에서 평가를 실행할 수 있습니다. 이 API는 세션, Amplitude에서 큐레이팅하는 데이터 세트 및 사용자가 정의하는 평가기 구성을 포함합니다. 오프라인 파이프라인은 제품에서 사용하는 것과 동일한 세션, 동일한 심사 기준 및 동일한 점수를 확인할 수 있습니다.

이 API는 읽기 전용입니다. 데이터를 전송하려면 AI SDK 없이 에이전트 이벤트 전송을 참조하십시오.

이러한 엔드포인트는 OpenAPI에서 정의한 Developer API에 포함되지 않으므로 해당 참조에 나타나지 않으며 amp CLI에서도 지원하지 않습니다. HTTP를 통해 직접 호출하십시오.

인증 및 요청 요구 사항

  • 모든 엔드포인트는 HTTP 기본 인증을 사용합니다. 프로젝트의 API 키를 사용자 이름으로 사용하고 비밀 키를 암호로 사용하십시오. API 키 및 비밀 키 찾기를 참조하십시오.
  • 인증된 프로젝트에 따라 어떤 데이터를 받을지 결정합니다. project_id 매개변수가 존재하지 않으며, 키는 다른 프로젝트의 데이터를 요청할 수 없습니다.
  • 페이지 매기기 커서는 불투명한 문자열입니다. 이전 응답에서 변경되지 않은 상태로 next_page_token을(를) 전달하십시오.
  • 하나의 트래버설 내 모든 페이지에서 sort_order 및 모든 필터를 동일하게 유지하십시오. 페이지네이션은 스냅샷이 아닌 라이브 데이터를 읽으므로 트래버스 중에 변경되는 데이터는 이후 페이지에 변경될 수 있습니다.

지역

프로젝트를 호스팅하는 데이터 센터로 요청을 보냅니다.

키는 지역 간에 상호 교환할 수 없습니다. US 프로젝트의 키는 EU 호스트에 대해 401을(를) 반환합니다.

Lookback 및 세션 가시성

두 가지 제품 규칙이 응답에 포함되는 내용을 결정하며, 둘 다 페이지 매기기 전에 적용됩니다:

  • Lookback window: 플랜의 자격 조건에 따라 세션을 사용할 수 있는 범위가 제한됩니다. 해당 창 외부의 명시적 시간 범위에 대한 요청은 범위를 좁히는 대신 400을(를) 반환합니다. 룩백 권한이 없는 조직은 세션 및 데이터 세트 엔드포인트를 사용할 수 없습니다. 시작하기 전에 자격을 할당합니다.
  • 세션 제한: 세션 제한에 도달한 조직은 새로운 세션을 내보낼 수 없습니다. 이미 강화된 세션은 계속 사용할 수 있습니다.

Amplitude는 세션을 조용히 삭제하는 것이 아니라 제외된 세션을 보고합니다. Collection 응답에는 필터가 제거한 내용과 이유를 계산하는 omissions 배열이 포함됩니다.

두 컬렉션 엔드포인트는 보류된 세션을 제외하고 omissions 항목에 계산합니다. 단일 세션 엔드포인트는 생략할 대상이 없기 때문에 대신 403을(를) 반환합니다.

생략 수는 현재 페이지가 아닌 전체 일치하는 컬렉션을 나타냅니다. 카운트는 모든 페이지에서 반복적으로 발생하므로 페이지 간에 더하지 마십시오.

세션 목록

메타데이터 및 수동 검토와 함께 인증된 프로젝트에 대한 페이지별 세션 목록을 반환합니다. Traces, spans 및 턴은 단일 세션 엔드포인트에서 제공됩니다.

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 }]
}

하나의 세션 받기

전체 추적, 스팬, 정제된 턴, 평가 결과, 보강 및 데이터 세트 멤버십이 포함된 하나의 세션을 반환합니다.

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 turn과 공급자 측의 요청 레코드 사이의 조인 키이며, 이로 인해 평가 점수를 공급자에게 다시 전송하거나 청구와 비용을 조정할 때 사용할 수 있는 필드입니다.

이 형식은 Amplitude의 형식이 아니라 공급자의 형식입니다. 일부 공급자는 chatcmpl-...와(과) 같은 접두어가 있는 문자열을 반환하고, 다른 공급자는 접두어가 없는 베어 토큰을 반환합니다. 값을 불투명하게 취급하십시오: 자체 레코드와 일치시키고, 구문 분석하거나 모양을 가정하지 마십시오.

이 값은 세 가지 경우에 null입니다. 완료가 없는 사용자 턴의 경우, 속성을 캡처하지 않는 계측기의 어시스턴트 턴의 경우, 필드가 존재하기 전에 Amplitude가 수집한 세션의 경우가 이에 해당합니다. 백필이 없으므로 부재한 ID를 오류가 아닌 틈새로 처리하십시오.

평가 결과

evaluations의 각 항목은 이번 세션에 대한 한 명의 평가자의 가장 최근 결과입니다. Amplitude는 대신 enrichments에 자체 내장 신호를 보고합니다.

Amplitude는 평가자가 생성한 대로 result전달하므로, 키는 다음과 같이 달라집니다:

대부분의 결과에는 결과를 설명하고 이를 뒷받침하는 대화의 내용을 rationale인용하는 내용도 포함되어 있습니다evidence.

이들은 완전한 목록이 아니라 브랜치할 가치가 있는 키입니다. 결과에는 평가자의 신뢰도 점수나 읽은 턴 수 등 다른 항목이 포함될 수 있으며, 해당 항목은 평가자 파이프라인의 변화에 따라 달라집니다. 필요한 키를 읽고 나머지는 무시하십시오.

result 또한 evaluator_id, status, cost_usd, latency_ms 등 여러 엔벨로프 필드를 반복합니다. envelope copy들을 권장합니다. Amplitude는 이를 이 참조로 문서화한 유형으로 정규화하지만, 내부의 값은 평가자가 작성한 대로 result 유지되며 정밀도가 다를 수 있습니다.

분류자 값을 브랜치를 위한 열거형으로 취급하지 말고, 표시 및 그룹화할 레이블로 처리하십시오. 평가 모델이 이를 생성하며, 평가자가 반환할 수 있는 값 집합은 해당 모델이나 프롬프트가 변경됨에 따라 변경될 수 있습니다. 파이프라인에 고정된 결과가 필요한 경우, 목록이 닫힌다고 가정하지 않고 관심 있는 값을 매핑하고 인식되지 않는 값을 처리하십시오.

공유 속성

시스템 프롬프트나 도구 정의와 같이 스팬 전체에 걸쳐 반복되는 span 속성은 세션 수준 shared_attributes 맵에 한 번 저장됩니다. 각 발생은 값 대신 참조를 포함합니다:

json
{ "$shared_attribute": "a1b2c3d4" }

shared_attributes에서 해당 값을 조회하여 참조를 해결합니다. 중복 제거는 무손실이며 응답을 몇 메가바이트에서 몇 백 킬로바이트로 줄일 수 있습니다. 반복되는 것이 없는 세션은 shared_attributes를 빈 객체로 반환합니다.

하나의 응답에서 반환할 수 없는 세션이 너무 크면 부분 데이터를 반환하는 것이 아니라 400로 실패합니다. 내보내기는 트레이스나 턴을 자동으로 자르지 않습니다.

데이터 세트 가져오기

ground-truth 레이블 및 human review를 포함하여 멤버 세션의 페이지로 구분된 목록이 포함된 데이터 세트를 반환합니다.

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

각 멤버는 세션 메타데이터만 전달합니다. 세션에 대해 개별적으로 트레이스와 턴을 요청합니다.

평가자 구성 가져오기

프롬프트, 모델 및 레이블을 포함하여 하나의 평가자 구성을 반환하므로 자체 툴링에서 동일한 판단을 재현할 수 있습니다.

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.

이 페이지에서