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및 모든 필터를 동일하게 유지하십시오. 페이지네이션은 스냅샷이 아닌 라이브 데이터를 읽으므로 트래버스 중에 변경되는 데이터는 이후 페이지에 변경될 수 있습니다.
지역
프로젝트를 호스팅하는 데이터 센터로 요청을 보냅니다.
| 지역 | 기본 URL |
|---|---|
| 미국 | https://developer-api.amplitude.com |
| EU | https://developer-api.eu.amplitude.com |
키는 지역 간에 상호 교환할 수 없습니다. US 프로젝트의 키는 EU 호스트에 대해 401을(를) 반환합니다.
Lookback 및 세션 가시성
두 가지 제품 규칙이 응답에 포함되는 내용을 결정하며, 둘 다 페이지 매기기 전에 적용됩니다:
- Lookback window: 플랜의 자격 조건에 따라 세션을 사용할 수 있는 범위가 제한됩니다. 해당 창 외부의 명시적 시간 범위에 대한 요청은 범위를 좁히는 대신
400을(를) 반환합니다. 룩백 권한이 없는 조직은 세션 및 데이터 세트 엔드포인트를 사용할 수 없습니다. 시작하기 전에 자격을 할당합니다. - 세션 제한: 세션 제한에 도달한 조직은 새로운 세션을 내보낼 수 없습니다. 이미 강화된 세션은 계속 사용할 수 있습니다.
Amplitude는 세션을 조용히 삭제하는 것이 아니라 제외된 세션을 보고합니다. Collection 응답에는 필터가 제거한 내용과 이유를 계산하는 omissions 배열이 포함됩니다.
두 컬렉션 엔드포인트는 보류된 세션을 제외하고 omissions 항목에 계산합니다. 단일 세션 엔드포인트는 생략할 대상이 없기 때문에 대신 403을(를) 반환합니다.
| 이유 | 의미 |
|---|---|
session_not_found | 데이터 세트 멤버의 세션이 더 이상 존재하지 않습니다. |
outside_lookback_window | 세션은 룩백 권한 범위를 벗어납니다. |
session_cap | 조직이 세션 상한에 도달했으므로 Amplitude는 해당 세션을 보류합니다. |
생략 수는 현재 페이지가 아닌 전체 일치하는 컬렉션을 나타냅니다. 카운트는 모든 페이지에서 반복적으로 발생하므로 페이지 간에 더하지 마십시오.
세션 목록
메타데이터 및 수동 검토와 함께 인증된 프로젝트에 대한 페이지별 세션 목록을 반환합니다. Traces, spans 및 턴은 단일 세션 엔드포인트에서 제공됩니다.
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 | 선택 사항입니다. 문자열입니다. 하나의 사용자 ID에 대한 세션을 반환합니다. |
agent_name | 선택 사항입니다. 문자열입니다. 한 에이전트에 대한 세션을 반환합니다. |
start_time | 선택 사항입니다. 시간대 오프셋이 있는 ISO 8601 문자열입니다. 세션 시작 시간의 하한값(포함)입니다. 룩백 창 외부의 값은 400을(를) 반환합니다. |
end_time | 선택 사항입니다. 시간대 오프셋이 있는 ISO 8601 문자열입니다. 세션 시작 시간의 상한값입니다(포함). 시작 시간보다 종료 시간이 이르면 400이(가) 반환됩니다. |
page_size | 선택 사항입니다. 1과 200 사이의 정수입니다. 기본값은 50입니다. |
page_token | 선택 사항입니다. 문자열입니다. 이전 응답의 next_page_token에 있는 불투명 커서입니다. |
sort_order | 선택 사항입니다. String. 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 | 필터가 제거한 세션 수(이유별)입니다. |
하나의 세션 받기
전체 추적, 스팬, 정제된 턴, 평가 결과, 보강 및 데이터 세트 멤버십이 포함된 하나의 세션을 반환합니다.
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 | 계측기가 전송한 그대로의 스팬 속성입니다. 키 세트는 SDK와 에이전트에 따라 다릅니다. |
traces[].spans[].raw_input | 메시지 콘텐츠를 사용할 수 있는 경우 span에 대한 텍스트를 입력합니다. |
traces[].spans[].raw_output | 메시지 콘텐츠를 사용할 수 있는 경우 span에 대한 출력 텍스트입니다. |
turns | 정렬된 턴 레코드입니다. 메시지 콘텐츠는 턴이 아닌 스팬에 존재합니다. |
turns[].created_at | 턴의 타임스탬프입니다. 이 값을 기준으로 정렬하여 대화를 순서대로 재구성합니다. |
turns[].provider_request_id | 컴플리션에 대한 모델 제공자 자체의 식별자입니다. 이를 사용하여 턴을 자신의 추론 기록에 결합하십시오. null 사용자 턴과, 계측 도구가 캡처하지 못한 어시스턴트 턴에 사용하십시오. 공급자 요청 ID를 참조하십시오. |
evaluations | 정의한 평가자의 결과로 평가자당 하나의 항목이 됩니다. 평가 결과를 참조하십시오. |
enrichments | Amplitude가 계산한 품질 신호, 주제 분류 및 루브릭 점수입니다. |
datasets | 이 세션이 속한 데이터 세트입니다. |
conversation_turn_count | 사용자가 대면하는 대화 턴의 횟수입니다. |
shared_attributes | 중복 제거된 스팬 속성입니다. 공유 속성을 참조하십시오. |
공급자 요청 ID
turns[].provider_request_id에는 모델 공급자가 완료에 할당한 식별자가 포함됩니다. Amplitude는 계측이 전송하는 gen_ai.response.id 속성에서 이를 읽습니다. 이는 Amplitude turn과 공급자 측의 요청 레코드 사이의 조인 키이며, 이로 인해 평가 점수를 공급자에게 다시 전송하거나 청구와 비용을 조정할 때 사용할 수 있는 필드입니다.
이 형식은 Amplitude의 형식이 아니라 공급자의 형식입니다. 일부 공급자는 chatcmpl-...와(과) 같은 접두어가 있는 문자열을 반환하고, 다른 공급자는 접두어가 없는 베어 토큰을 반환합니다. 값을 불투명하게 취급하십시오: 자체 레코드와 일치시키고, 구문 분석하거나 모양을 가정하지 마십시오.
이 값은 세 가지 경우에 null입니다. 완료가 없는 사용자 턴의 경우, 속성을 캡처하지 않는 계측기의 어시스턴트 턴의 경우, 필드가 존재하기 전에 Amplitude가 수집한 세션의 경우가 이에 해당합니다. 백필이 없으므로 부재한 ID를 오류가 아닌 틈새로 처리하십시오.
평가 결과
evaluations의 각 항목은 이번 세션에 대한 한 명의 평가자의 가장 최근 결과입니다. 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에 따라 달라집니다. |
Amplitude는 평가자가 생성한 대로 result전달하므로, 키는 다음과 같이 달라집니다:
| Evaluator 유형 | 키 |
|---|---|
| Rubric | score, normalized_score |
| Classifier | primary, secondary |
| Detector | detected, signals |
대부분의 결과에는 결과를 설명하고 이를 뒷받침하는 대화의 내용을 rationale인용하는 내용도 포함되어 있습니다evidence.
이들은 완전한 목록이 아니라 브랜치할 가치가 있는 키입니다. 결과에는 평가자의 신뢰도 점수나 읽은 턴 수 등 다른 항목이 포함될 수 있으며, 해당 항목은 평가자 파이프라인의 변화에 따라 달라집니다. 필요한 키를 읽고 나머지는 무시하십시오.
result 또한 evaluator_id, status, cost_usd, latency_ms 등 여러 엔벨로프 필드를 반복합니다. envelope copy들을 권장합니다. Amplitude는 이를 이 참조로 문서화한 유형으로 정규화하지만, 내부의 값은 평가자가 작성한 대로 result 유지되며 정밀도가 다를 수 있습니다.
분류자 값을 브랜치를 위한 열거형으로 취급하지 말고, 표시 및 그룹화할 레이블로 처리하십시오. 평가 모델이 이를 생성하며, 평가자가 반환할 수 있는 값 집합은 해당 모델이나 프롬프트가 변경됨에 따라 변경될 수 있습니다. 파이프라인에 고정된 결과가 필요한 경우, 목록이 닫힌다고 가정하지 않고 관심 있는 값을 매핑하고 인식되지 않는 값을 처리하십시오.
공유 속성
시스템 프롬프트나 도구 정의와 같이 스팬 전체에 걸쳐 반복되는 span 속성은 세션 수준 shared_attributes 맵에 한 번 저장됩니다. 각 발생은 값 대신 참조를 포함합니다:
{ "$shared_attribute": "a1b2c3d4" }
shared_attributes에서 해당 값을 조회하여 참조를 해결합니다. 중복 제거는 무손실이며 응답을 몇 메가바이트에서 몇 백 킬로바이트로 줄일 수 있습니다. 반복되는 것이 없는 세션은 shared_attributes를 빈 객체로 반환합니다.
하나의 응답에서 반환할 수 없는 세션이 너무 크면 부분 데이터를 반환하는 것이 아니라 400로 실패합니다. 내보내기는 트레이스나 턴을 자동으로 자르지 않습니다.
데이터 세트 가져오기
ground-truth 레이블 및 human review를 포함하여 멤버 세션의 페이지로 구분된 목록이 포함된 데이터 세트를 반환합니다.
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 | 이 세션에 대해 사람이 검증한 레이블입니다. evaluator_results는 평가자 ID를 검증된 판정 결과에 매핑하고 overridden_evaluators는 검토자가 수정한 평가자를 나열합니다. |
members[].ground_truth_labels.review_status | 검토 완료도(예: partial 또는 verified). |
members[].session | 세션 메타데이터로, 세션 목록이 반환하는 것과 동일한 형태입니다. |
각 멤버는 세션 메타데이터만 전달합니다. 세션에 대해 개별적으로 트레이스와 턴을 요청합니다.
평가자 구성 가져오기
프롬프트, 모델 및 레이블을 포함하여 하나의 평가자 구성을 반환하므로 자체 툴링에서 동일한 판단을 재현할 수 있습니다.
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.