에이전트 분석 택소노미
에이전트 분석은 관리형 이벤트 택소노미를 사용합니다. 모든 이벤트 이름과 속성에는 [Agent]이(가) 접두사로 붙으므로, 에이전트 데이터는 동일한 프로젝트 내에서도 제품 이벤트와 명확하게 분리되어 유지됩니다. 동일한 프로젝트와 동일한 사용자 ID를 공유하므로, 에이전트 및 제품 동작 전반에 걸쳐 차트를 만들고, 세그먼트를 분류하고, 코호트를 구축할 수 있습니다.
이 페이지는 에이전트 분석에서 생성하는 모든 이벤트 및 속성에 대한 참조입니다. 이벤트는 두 가지 프로듀서에서 제공됩니다.
- SDK 계측은 에이전트가 실행되는 동안 실시간으로 이벤트를 발생시킵니다: 사용자 메시지, AI 응답, 도구 호출, Span, Embedding, 세션 종료, 세션 보강 및 점수.
- Amplitude의 보강 파이프라인은 세션이 종료된 후 Session Record 및 Evaluator Result 이벤트를 발생시킵니다. Amplitude는 결코 점수 이벤트를 발생시키지 않습니다. 점수는 항상 애플리케이션에서 발생합니다.
데이터 계층 구조
에이전트 분석은 각 에이전트 상호 작용을 계층 구조로 모델링합니다.
| 레벨 | 무엇인가요? | 식별 기준 |
|---|---|---|
| 세션 | 사용자가 에이전트에게 전달하는 작업 단위 중 하나입니다: 대화 스레드, 지원 티켓, 음성 통화, 백그라운드 실행. | [Agent] Session ID |
| 턴 | 세션 내 한 번의 교환: 사용자 메시지, 에이전트의 도구 호출 및 AI 응답. | [Agent] Turn ID |
| 스팬 | 한 턴 내 한 작업: LLM 호출, 도구 호출, 검색 단계 또는 사용자가 추적하는 모든 사용자 지정 작업. | 각 이벤트의 Span-level ID |
에이전트는 모든 이벤트의 차원입니다: 모든 이벤트는 [Agent] Agent ID 속성을 가지며, 다중 에이전트 시스템에서 하위 에이전트는 [Agent] Parent Agent ID 속성을 갖습니다. 단일 세션에 여러 에이전트가 포함될 수 있습니다. 세션 수준 롤업은 [Agent] Root Agent Name(세션을 시작한 에이전트) 및 [Agent] Agent Chain Depth(가장 긴 위임 경로에 있는 에이전트 수)을(를) 기록합니다. 에이전트를 비교하려면 차트를 [Agent] Agent ID(으)로 그룹화하십시오. 다중 에이전트 세션을 분석하려면 체인 깊이가 1보다 큰 세션 레코드를 필터링합니다.
에이전트 세션은 분석 세션이 아닙니다: [Agent] Session ID은(는) 에이전트 작업 단위를 식별하며 귀하의 계측에 의해 설정됩니다(앱에 이미 있는 스레드, 티켓, 호출 또는 실행 ID를 사용하십시오). Amplitude의 표준 session ID은(는) 앱 또는 웹 방문을 식별하고 세션 리플레이를 지원합니다. 하나의 분석 세션에 여러 에이전트 세션이 포함될 수 있습니다. 세션 리플레이를 위해 두 가지를 연결하려면 에이전트 세션을 세션 리플레이에 연결을 참조하십시오.
이벤트 인벤토리
| 이벤트 | 프로듀서 | 발생할 때 |
|---|---|---|
[Agent] User Message | SDK | 사용자가 에이전트에게 메시지를 보냅니다. 턴을 엽니다. |
[Agent] AI Response | SDK | 모델은 응답을 반환합니다. 모델, 토큰, 비용 및 지연 시간을 전달합니다. |
[Agent] Tool Call | SDK | 에이전트가 도구 또는 함수를 호출합니다. |
[Agent] Span | SDK | observe() 또는 trackSpan()(으)로 추적하는 모든 사용자 지정 작업. |
[Agent] Embedding | SDK | RAG 및 검색 워크로드를 위한 임베딩 호출입니다. |
[Agent] Session End | SDK | 앱이 작업 단위를 완료로 표시합니다. 선택 사항입니다. 아래의 세션 닫기를 참조하십시오. |
[Agent] Session Enrichment | SDK | 세션에 고유한 레이블과 점수를 첨부합니다. 모든 개인정보 보호 모드에서 사용할 수 있습니다. |
[Agent] Score | SDK | 앱은 사용자의 엄지손가락 평가, LLM 심사 위원, 인간 검토자 등 피드백을 기록합니다. Amplitude는 이 이벤트를 생성하지 않습니다. |
[Agent] Session Record | 서버 | 닫힌 세션당 한 번. 모든 신호 결과와 세션 롤업을 전달합니다. |
[Agent] Evaluator Result | 서버 | 닫힌 세션당 활성 사용자 지정 평가자당 한 번. |
사용 중단된 이벤트
사용 중단됨: [Agent] Topic Classification은(는) 더 이상 발생하지 않습니다. 주제 및 분류 출력은 이제 [Agent] Evaluator Result(분류 유형)에 기록되며, 세션 레코드 내[Agent] Topic Summary에 표시됩니다. 주제 분류(Topic Classification)를 기반으로 차트를 구축한 경우 Evaluator Result로 마이그레이션하십시오.
신호: 품질이 보장되는 곳
Amplitude는 모든 종료된 세션에서 고정된 품질 신호 세트를 실행합니다. 신호 결과는 [Agent] Session Record 이벤트의 속성으로 표시되며, 세션당 하나의 레코드로 각 신호는 고유한 결과, 근거 및 (해당되는 경우) 증거 속성을 갖습니다. 신호는 별도의 이벤트를 생성하지 않습니다. 각 신호가 응답하는 내용과 해당 레이블이 의미하는 내용은 Agent Analytics 내장 신호를 참조하십시오.
| 신호 | 결과 속성 | 유형 | 관련 속성 |
|---|---|---|---|
| 작업 완료 | [Agent] Task Completed | 부울입니다 | 근거, 증거 |
| 응답 품질 | [Agent] Response Quality | 부울입니다 | 근거, 증거 |
| 사용자 의도 | [Agent] User Intent | 분류 | 근거 |
| 세션 안전 | [Agent] Session Safety | 분류 | 근거 |
| 사용자 마찰 | [Agent] Has User Friction | 부울입니다 | 근거, [Agent] Detected User Friction(패턴) |
| 부정적인 피드백. | [Agent] Has Negative Feedback | 부울입니다 | 근거, [Agent] Detected Negative Feedback(구문) |
| 데이터 품질 | [Agent] Has Data Quality Issues | 부울입니다 | 근거, 증거, [Agent] Detected Data Quality Issues(이슈 목록) |
신호 의미론에 대한 참고 사항:
- 모든 신호는 근거를 작성합니다. 작업 완료됨, 응답 품질 및 데이터 품질도 증거를 작성할 수 있습니다. 신호는 방향성 지표이며 기본 사실이 아닙니다.
- 작업 완료됨 및 응답 품질은 숫자 점수가 아닌 부울입니다. 트렌드를 확인하려면 값이 true인 세션의 비율을 차트로 표시합니다. Task Completed는 초기 오류 후 성공이 발생할 때 복구에 대해 크레딧을 부여하며 톤은 무시합니다. 응답 품질은 작업 결과와 무관하게 텍스트(정확하고, 명확하며, 구조화됨)를 판단합니다.
- 부정적 피드백과 사용자 마찰은 연관되어 있지만 구별됩니다. 부정적 피드백은 사용자가 작성한 내용에 대한 명시적 불만족을 감지합니다. 사용자 마찰은 사용자가 불평을 하지 않더라도 재시도 폭풍과 설명 루프와 같은 행동 패턴을 감지합니다.
- 앱이 전송하는 Thumb Down 또는 낮은 평가는
[Agent] Score부정적 피드백에 대한 명시적 불만족으로 간주됩니다. 사용자 피드백 수집을 참조하십시오. - 대부분의 신호에는 메시지 텍스트가 필요합니다. 세션에
metadata_only및customer_enriched와(과) 같이 아무것도 포함되지 않은 경우, 이러한 신호 속성은 실패로 보고되지 않고 세션 레코드에서 제외됩니다. 데이터 품질 보고는 여전히 활성화되어 있습니다. 각 모드가 전송하는 내용을 참조하십시오.
분류 값:
[Agent] User Intent: 정보 요청, 분석 및 합성, 작업 실행, 콘텐츠 생성, 조언 및 추천, 주제 외 / 소셜. 인사말이 아닌 세션 전반에 걸쳐 지배적 인텐트에 따라 분류됩니다.[Agent] Session Safety: 일반(기본값), 주제외(Off-Topic), 프롬프트 삽입, 남용, Probing, 안전하지 않은 출력(에이전트가 유해한 콘텐츠를 생성함), 데이터 유출(에이전트가 PII, 자격 증명 또는 내부 정보를 노출함).
공통 속성
이들은 모든 또는 대부분의 SDK 이벤트에 나타납니다:
| 속성 | 유형 | 설명 |
|---|---|---|
[Agent] Session ID | 문자열 | 이 이벤트가 속한 에이전트 세션입니다. 하나를 전달하지 않는 경우 자동 생성됩니다. 프로덕션에서는 항상 실제 스레드, 티켓, 콜 또는 run ID를 전달합니다. |
[Agent] Turn ID | 숫자 | 세션 내 턴 순서입니다. 교환당 하나의 값을 사용합니다: 사용자 메시지, 도구 호출 및 AI 응답은 모두 동일한 Turn ID를 사용합니다. 한 턴 내 순서는 이벤트 시간에 따라 결정됩니다. |
[Agent] Trace ID | 문자열 | 세션 내에서 관련 작업을 그룹화합니다. |
[Agent] Agent ID | 문자열 | 이 이벤트를 생성한 에이전트입니다. 필수: 이 정보가 없으면 에이전트 분석(Agent Analytics) 소비자는 여전히 이벤트를 수락하지만(HTTP API가 200을(를) 반환함), 세션에 상호 연결할 수 없으므로 잘못 그룹화되어 에이전트 분석(Agent Analytics) 뷰에서 제외됩니다. |
[Agent] Parent Agent ID | 문자열 | 이 에이전트로 위임한 에이전트입니다. 루트 에이전트에는 없습니다. 상위 스팬 ID는 상위 에이전트가 아닙니다. |
[Agent] Message Source | 문자열 | 사용자 메시지: user 최종 사용자 턴의 경우, agent 상위 에이전트가 프롬프트를 전달했을 때. 명시적 값이 우선합니다. |
[Agent] Customer Org ID | 문자열 | B2B 에이전트의 테넌트 식별자입니다. |
[Agent] Env | 문자열 | 배포 환경(예: 프로덕션). |
[Agent] Runtime | 문자열 | 이벤트를 발생시킨 런타임(예: browser). |
[Agent] SDK Version | 문자열 | Amplitude AI SDK의 버전입니다. 진단 필드입니다. 앱 버전으로 덮어쓰지 말고, 대신 에이전트 버전 관리를 사용하십시오. |
[Agent] Context | 문자열 (JSON) | 에이전트 생성 시 첨부하는 임의의 키-값 컨텍스트(surface, 프롬프트 개정, 배포 영역)입니다. A/B 테스트 및 기능 플래그 변형의 경우 실험 속성을 사용하십시오. |
[Agent] Experiments | 문자열 배열 | 이벤트가 실행된 실험, key:variant 문자열로 표시됨. SDK experiments옵션 또는 OpenTelemetry feature_flag.*속성에서 설정합니다. 실험 변형 기록을 참조하십시오. |
[Agent] Experiment Key | 문자열 | 정확히 하나의 실험이 적용되는 경우 실험 또는 플래그 키입니다. |
[Agent] Experiment Variant | 문자열 | 정확히 하나의 실험이 적용되는 경우 변형입니다. 차트를 해당 항목으로 그룹화하여 실험군을 비교합니다. |
[Agent] Experiment Unit | 문자열 | 플래그 클라이언트가 무작위로 지정한 값, 정확히 하나의 실험이 적용되는 경우: agent_session, turn 또는 span. |
[Agent] Experiment Provider | 문자열 | 플래그 또는 실험 시스템(예: statsig), 정확히 하나의 실험이 적용되고 사용자가 설정한 경우. |
[Agent] Git SHA | 문자열 | 프로세스가 빌드된 Commit SHA. SDK 스타트업 시 AMPLITUDE_GIT_SHA(또는 GIT_SHA)에서 읽습니다. Capture 배포 메타데이터를 참조하십시오. |
[Agent] Git Ref | 문자열 | Git ref(일반적으로 브랜치 또는 태그)로서, 프로세스가 구축된 기반. SDK 스타트업 시 AMPLITUDE_GIT_REF(또는 GIT_REF)에서 읽습니다. |
[Agent] Git Repo | 문자열 | 저장소 URL입니다. AMPLITUDE_GIT_REPO(또는 GIT_REPO)을(를) 통해 옵트인하십시오. SDK는 user:pass@ userinfo를 모두 제거하여 값을 정제합니다. |
이벤트 계약
AI SDK는 필요한 속성을 대신 채웁니다. 표준 Amplitude SDK 또는 HTTP API를 통해 이벤트를 직접 전송할 때, 각 이벤트는 아래의 공유 속성과 해당 이벤트 유형에 필요한 속성을 포함해야 합니다. 단계는 AI SDK 없이 에이전트 이벤트 전송을 참조하십시오.
모든 이벤트의 공유 속성: [Agent] Session ID, [Agent] Turn ID, [Agent] Trace ID, [Agent] Agent ID, [Agent] Env, [Agent] Runtime, 및 (선택 사항) [Agent] Context 및 실험 속성. 프로덕트 분석에 사용하는 것과 동일한 user_id을(를) 전송하고, 이벤트당 고유 insert_id을(를) 전송하여 재시도 시 중복이 발생하지 않도록 하십시오.
| 이벤트 | 공유 속성 외에 필수 | 참고 사항 |
|---|---|---|
[Agent] User Message | [Agent] Message ID, 개인정보 보호 모드가 콘텐츠를 전송할 때 $llm_message: { text } | 요청 시작 시 Emit. |
[Agent] Tool Call | [Agent] Invocation ID, [Agent] Tool Name, [Agent] Tool Success, [Agent] Latency Ms, [Agent] Parent Message ID | 호출당 하나의 이벤트로, AI 응답 전에 실행 순서대로 발생합니다. 도구 페이로드는 [Agent] Tool Input 및 [Agent] Tool Output에 들어가며 편집 처리됩니다. |
[Agent] AI Response | [Agent] Message ID, [Agent] Model Name, [Agent] Provider, [Agent] Latency Ms, 토큰 수, 계산하는 경우 [Agent] Cost USD, 콘텐츠를 보낼 때 $llm_message: { text } | 시스템 프롬프트는 이 이벤트의 속성([Agent] System Prompt)이며 별도의 이벤트가 아닙니다. |
[Agent] Session End | 선택 사항: [Agent] Output State, [Agent] Abandonment Turn, [Agent] Session Idle Timeout Minutes | close-reason 또는 duration 속성을 임의로 생성하지 마십시오. 서버는 세션 레코드에 대해 파생 [Agent] Close Reason및 롤업을 수행합니다. |
[Agent] Score | [Agent] Score Name, [Agent] Score Value, [Agent] Target ID, [Agent] Target Type, [Agent] Evaluation Source | SDK가 있거나 없는 경우 동일한 계약. |
Wire-format 규칙:
$llm_message은(는) 객체입니다:{ "text": "..." }. Amplitude는 일반 문자열을 무시하며, 스레드 뷰에는 콘텐츠가 표시되지 않습니다.- Turn ID는 이벤트가 아닌 교환을 식별합니다: 사용자 메시지 왕복 시 Turn ID를 1회 증가시키고, 해당 교환의 사용자 메시지, 모든 도구 호출 및 AI 응답에 동일한 값을 스탬프하십시오. 왕복 트립당
[Agent] Trace ID하나를 생성하고 동일한 이벤트 간에 공유합니다. 한 턴 내의 순서는 이벤트 시간에 따라 결정됩니다. - 토큰과 비용은 AI Response에만 적용됩니다. 도구 호출은 토큰을 소비하지 않습니다. 서버는 모든 이벤트의 합계
[Agent] Cost USD를 계산하므로 다른 이벤트 유형의 비용은 세션 합계를 증가시킵니다. [Agent] Agent ID은(는) 필수입니다: 이 정보가 없으면 HTTP API가200을(를) 반환하지만 에이전트 분석은 해당 이벤트를 세션으로 그룹화할 수 없습니다.- 접두사 속성: 세션 리플레이 ID는
[Amplitude] Session Replay ID이지만, 그 외의 모든 에이전트 속성 이름은[Agent]으(로) 시작합니다.
이벤트 속성 참조
[에이전트] 사용자 메시지
| 속성 | 유형 | 참고 사항 |
|---|---|---|
[Agent] Message ID | 문자열 | 이 메시지의 고유 ID입니다. 이를 Score target으로 참조하십시오. |
$llm_message.text | 문자열 | 메시지 콘텐츠입니다. 개인정보 보호 모드가 콘텐츠를 전송할 때만 표시됩니다. |
[Agent] System Prompt | 문자열 | 시스템 프롬프트가 적용됩니다. 선택 필드이며, 개인정보 보호 모드에 의해 제한됩니다. |
[Agent] Input State | 문자열 | 메시지가 전송되었을 때의 애플리케이션 상태입니다. |
[Agent] Is Regeneration | 부울 | 사용자가 이전 응답을 재실행하도록 요청했습니다. 암시적 부정 신호입니다. |
[Agent] Is Edit / [Agent] Edited Message ID | boolean / string | 사용자가 이전 메시지를 수정했으며, 원본으로 연결됩니다. |
| 첨부 파일 속성 | 혼합 | Has Attachments, Attachment Count, Attachment Types, Total Attachment Size Bytes, Attachments. |
[에이전트] AI 응답
| 속성 | 유형 | 참고 사항 |
|---|---|---|
[Agent] Message ID | 문자열 | 고유 ID입니다. Score target으로 참조하십시오. |
[Agent] Model Name | 문자열 | 응답을 생성한 모델입니다(예: gpt-4o). |
[Agent] Provider | 문자열 | 모델 공급자(예: openai, anthropic). |
[Agent] Model Tier | 문자열 | fast, standard 또는 reasoning; 모델 이름에서 추정됩니다. |
[Agent] Input Tokens / [Agent] Output Tokens / [Agent] Total Tokens | 숫자 | 토큰 사용. |
[Agent] Cache Read Tokens / [Agent] Cache Creation Tokens | 숫자 | 공급자 캐시 분석을 전달할 때 나타나며, 정확한 혼합 비용을 활성화합니다. |
[Agent] Cost USD | 숫자 | 토큰 및 모델 과금 체계에서 자동 계산되거나 직접 전달하는 값입니다. 모델의 가격을 책정할 수 없는 경우 생략되었습니다. |
[Agent] Latency Ms | 숫자 | 호출의 실제 소요 시간입니다. |
[Agent] TTFB Ms | 숫자 | 스트리밍 응답을 위한 첫 번째 바이트까지의 시간입니다. |
[Agent] Temperature | 숫자 | 샘플링 온도입니다. |
[Agent] Finish Reason | 문자열 | 생성이 중지된 이유입니다. |
[Agent] Is Error / [Agent] Error Message | boolean / string | 호출이 실패했는지 여부와 그 이유입니다. |
[Agent] Is Streaming | 부울 | 응답이 스트리밍되었습니다. |
[Agent] Was Copied | 부울 | 사용자가 출력을 복사했습니다. 암시적 양성 신호입니다. |
$llm_message.text | 문자열 | 개인정보 보호 모드로 관리되는 응답 콘텐츠입니다. |
[에이전트] 도구 호출
| 속성 | 유형 | 참고 사항 |
|---|---|---|
[Agent] Tool Name | 문자열 | 호출된 도구의 이름입니다. |
[Agent] Invocation ID | 문자열 | 이 도구 호출에 대한 고유 ID입니다. |
[Agent] Parent Message ID | 문자열 | 호출을 트리거한 사용자 메시지의 [Agent] Message ID값입니다. |
[Agent] Tool Input / [Agent] Tool Output | 문자열 | 도구 페이로드. 개인정보 보호 모드로 제한됩니다. |
[Agent] Tool Success | 부울 | 도구 호출이 성공했는지 여부입니다. |
[Agent] Is Error / [Agent] Error Message | boolean / string | 실패 세부 정보. |
[Agent] Latency Ms | 숫자 | 도구 실행 시간입니다. |
[Agent] Span 및 [Agent] Embedding
스팬에는 [Agent] Span Name, [Agent] Latency Ms, [Agent] Input State, [Agent] Output State, [Agent] Is Error, 선택적 상위 스팬 중첩 및 사용자가 첨부한 모든 속성이 포함됩니다. Embedding은 AI Response와 같이 모델, 공급자, 토큰 및 비용 속성을 포함합니다. Embedding 이벤트는 세션 파이프라인에 참여하지 않습니다. 즉, 유휴 시계를 재설정하지 않으며 해당 비용은 세션 비용 USD에 포함되지 않습니다.
[에이전트] 세션 종료
생애주기 분석 및 시간 초과 규칙에 대한 자세한 내용은 세션 닫기 방법을 참조하십시오.
| 속성 | 유형 | 참고 사항 |
|---|---|---|
[Agent] Output State | 문자열 | 세션의 최종 애플리케이션 상태입니다. |
[Agent] Abandonment Turn | 숫자 | 사용자가 떠난 후의 턴입니다. 값이 낮으면 첫 번째 응답 불만족을 강력하게 나타냅니다. |
[Agent] Session Idle Timeout Minutes | 숫자 | 이 세션을 자동으로 닫기 전에 얼마나 기다려야 하는지를 서버에 알려줍니다. 기본값은 30. |
[에이전트] 점수
애플리케이션의 피드백 이벤트입니다. Amplitude는 절대로 점수를 생성하지 않습니다. 프로젝트의 모든 Score는 코드에서 score() 또는 trackScore()을(를) 통해 제공됩니다.
| 속성 | 유형 | 참고 사항 |
|---|---|---|
[Agent] Score Name | 문자열 | 할당한 이름(예: user-feedback, quality)입니다. user-feedback 이름은 세션에서 감지된 부정적 피드백 신호를 무시하는 특별한 의미를 가집니다. |
[Agent] Score Value | 숫자 | 숫자 값입니다. 엄지 아이콘에는 0 및 1을 사용하거나, 사용자가 정의한 척도를 사용하십시오. |
[Agent] Target ID | 문자열 | [Agent] Message ID또는 [Agent] Session ID점수를 받는 것입니다. |
[Agent] Target Type | 문자열 | message 또는 세션. |
[Agent] Evaluation Source | 문자열 | 사용자, AI 또는 검토자: 판단을 작성한 사람입니다. |
[Agent] Comment | 문자열 | 선택적 무료 텍스트입니다. 개인정보 보호 모드로 게이트됩니다. |
[에이전트] 세션 보강
사용자 고유의 세션 수준 레이블: 품질 점수, 결과, 인프라에서 계산된 주제.trackSessionEnrichment() 또는 setEnrichments()을(를) 통해 전송됨. 모든 개인정보 보호 모드에서 작동하며, customer_enriched 모드의 기본 데이터 경로입니다.
[에이전트] 세션 기록
세션이 닫힌 후 세션당 한 번씩 발생합니다. 이는 품질 분석을 위한 핵심 이벤트입니다. 세션당 한 행에 모든 신호 결과 및 롤업이 포함됩니다. 세션당 정확히 하나의 세션 레코드가 있습니다.
세션 ID 및 롤업:
| 속성 | 유형 | 참고 사항 |
|---|---|---|
[Agent] Session ID | 문자열 | 세션. |
[Agent] Root Agent Name | 문자열 | 세션을 시작한 에이전트입니다. |
[Agent] Agent Chain Depth | 숫자 | 가장 긴 위임 경로에 있는 에이전트입니다. 1은 단일 에이전트이고, 2는 한 홉이며, 3 이상은 더 깊습니다. 깊이(Depth)가 1보다 크면 다중 에이전트임을 의미합니다. |
[Agent] Close Reason | 문자열 | explicit_close 또는 timeout. |
[Agent] Turn Count | 숫자 | 세션 내 턴. |
[Agent] Session Total Tokens | 숫자 | 토큰 롤업. |
[Agent] Session Cost USD | 숫자 | 세션에 대한 비용 롤업입니다. |
[Agent] Session Avg Latency Ms | 숫자 | 평균 응답 지연 시간입니다. |
[Agent] Models Used | 배열 | 세션에서 관찰된 모든 모델. |
[Agent] Technical Error Count | 숫자 | 세션 전체의 오류. |
[Agent] Topic Summary | 문자열 | 세션 내용에 대한 모델 작성 요약. |
[Agent] Taxonomy Version | 문자열 | Amplitude가 이 레코드를 생성할 때 조직에 대해 게시된 평가 구성의 ID입니다. 이 에이전트의 평가자가 변경되지 않았더라도 조직 내에서 누군가가 평가자를 게시할 때마다 변경되므로, [Agent] Signal Versions을(를) 사용하여 신호가 변경되었는지 확인하십시오. |
[Agent] Signal Versions | 배열 | 이 세션에 대해 결과를 생성한 내장 신호는 각각 <signal>@<version>와(과) 같은 task_completion@2입니다. Amplitude가 이러한 신호 중 하나를 업데이트할 때만 변경됩니다. |
[Agent] Evaluated At / [Agent] Evaluation Source | timestamp / string | 보강이 실행된 경우; 소스는 ai입니다. |
신호 결과(의미론은 위의 신호 표를 참조하십시오):
| 속성 | 유형 |
|---|---|
[Agent] Task Completed Plus Rationale and Evidence | boolean, 문자열 |
[Agent] Response Quality, Plus Rationale 및 Evidence | boolean, 문자열 |
[Agent] User Intent, Plus Rationale | classification, 문자열 |
[Agent] Session Safety, Plus Rationale | classification, 문자열 |
[Agent] Has User Friction, Plus Rationale 및 [Agent] Detected User Friction | boolean, string, array |
[Agent] Has Negative Feedback, Plus Rationale 및 [Agent] Detected Negative Feedback | boolean, string, array |
[Agent] Has Data Quality Issues, Plus [Agent] Detected Data Quality Issues | boolean, array |
[Agent] Has Technical Failure | 부울 |
[Agent] Has User Feedback / [Agent] User Score | boolean / number, 앱이 사용자 피드백 점수를 전송했을 때 존재함 |
[Agent] Evaluator Result
닫힌 세션당 활성 사용자 지정 평가자당 한 번씩 발생합니다. 사용자 지정 평가자는 Amplitude UI에서 정의하고 조정하는 평가자이며, 내장 신호는 Evaluator Result 이벤트를 생성하지 않습니다.
평가자 ID 및 출력:
| 속성 | 유형 | 참고 사항 |
|---|---|---|
[Agent] Evaluator Name | 문자열 | 평가자(예: 완료된 상호 작용). |
[Agent] Evaluator Output Type | 문자열 | 이진, 분류 또는 점수입니다. |
[Agent] Evaluator ID | 문자열 | 평가자의 안정적 ID입니다. 버전 및 이름 변경 전반에 걸쳐 동일하게 유지되므로, 이를 사용하여 시간별로 한 평가자를 추적하십시오. |
[Agent] Evaluator Version | 문자열 | 평가자의 버전, 1, 2, 3 등입니다. 평가자를 편집하고 승격할 때마다 상승합니다. Amplitude가 평가자 버전을 추적하기 전에 발생한 이벤트의 경우 이 항목에는 대신 조직 전체 구성 ID가 포함됩니다. |
[Agent] Evaluator Model | 문자열 | judge 모델, 형식이 지정된 provider:model(예: openai:gpt-5-mini)입니다. |
[Agent] Evaluator Enrichment Cost USD | 숫자 | 이 평가를 실행하는 데 드는 비용입니다. |
[Agent] Binary Label / [Agent] Binary Value | boolean / number | 바이너리 평가자의 경우의 결과입니다. |
[Agent] Primary Label / [Agent] Subcategories | string / array | 결과는 분류 평가자를 위한 것입니다. |
[Agent] Score Value / [Agent] Score Label | number / string | 점수 평가자의 경우의 결과입니다. |
[Agent] Evaluated At / [Agent] Evaluation Source | timestamp / string | 실행 시, 소스는 AI였습니다. |
모든 평가자 결과에 복제되는 세션 차원으로, 세션 레코드에 조인하지 않고도 평가자 결과를 세그먼트화할 수 있습니다: [Agent] Root Agent Name, [Agent] Agent Chain Depth, [Agent] Close Reason, [Agent] Turn Count, [Agent] Session Total Tokens, [Agent] Session Cost USD, [Agent] Session Avg Latency Ms, [Agent] Models Used, [Agent] Technical Error Count, [Agent] Topic Summary, Has 플래그, 그리고 존재하는 경우 [Agent] User Score.
비용이 계산되는 방법
[Agent] Cost USD은(는) SDK에서 이벤트가 추적되는 순간에 정확히 한 번 계산됩니다. 다운스트림에서는 이를 재계산하지 않습니다. 서버가 값을 그대로 읽고 합산합니다. 자동 과금 체계는 이벤트의 토큰 수를 지속적으로 유지되는 오픈 소스 모델 가격 카탈로그(SDK와 함께 번들로 제공되는 Pydantic의 genai-prices 프로젝트)와 곱하므로, 표준 모델 식별자가 중요합니다. 명시적으로 전달하는 비용은 항상 자동 과금 체계에 비해 우선하며, 0을 포함하여 주어진 대로 발생합니다.
가격이 책정되는 것과 그렇지 않은 것:
- 캐시-인식 블렌딩. 캐시 토큰 분석을 사용하면 캐시되지 않은 입력, 캐시 읽기 및 캐시 쓰기에 각각 고유한 요금이 적용됩니다. 이 분석이 없으면 캐시가 많은 워크로드의 비용이 2~5배 과다 산정될 수 있습니다.
- 가격을 책정할 수 없는 모델. SDK는 비표준 이름, 게이트웨이 별칭(예:
openrouter/auto) 또는 미세 조정된ft:모델 이름에 대해 자동으로 가격을 책정할 수 없습니다. 속성을 생략하고 모델당 한 번씩 경고를 기록합니다. 미세 조정된 모델이나 사용자 지정 모델의 경우 직접 비용을 전달하십시오. - 과금 체계의 최신성. 과금 체계 정보는 SDK의 번들형 카탈로그와 함께 제공되며, SDK는 기본적으로 업데이트를 가져오지 않습니다. 새로 출시된 모델의 경우 시작 시
enableLivePriceUpdates()(Node) 또는enable_live_price_updates()(Python)을(를) 호출하여 시간별로 가격을 새로 고칩니다. 새로 고침이 실패하면 SDK는 계속 번들로 제공되는 카탈로그를 사용합니다. 라이브 업데이트는 기존 이벤트의 가격을 조정하지 않습니다. 구성 세부 정보는 과금 체계 데이터를 최신 상태로 유지하기를 참조하십시오.
SDK를 통하지 않고 이벤트를 직접 전송하는 경우, 비용을 직접 제공하십시오. HTTP 이벤트의 경우 [Agent] Cost USD을(를), OTLP 스팬의 경우 gen_ai.usage.cost을(를) 제공하십시오. Amplitude는 사용자가 전송하는 값을 저장하며, 직접 이벤트는 정확한 예측에 필요한 모든 입력값을 포함하지 않을 수 있으므로 가격을 조정하지 않습니다.
세션 기록의 [Agent] Session Cost USD은(는) 세션의 [Agent] AI Response 이벤트에 걸친 [Agent] Cost USD의 합계이며, 이는 전부 아니면 없음 방식으로 작동합니다. 즉, 토큰 사용량이 있는 이벤트 중 비용이 발생하지 않는 이벤트(예: 가격이 책정되지 않은 모델)가 하나라도 있으면, 해당 속성은 부분 합계를 보고하는 대신 해당 속성이 세션 레코드에서 완전히 생략됩니다. Embedding 이벤트는 세션 파이프라인에 참여하지 않으므로 Embedding 비용은 영향을 주지 않습니다. 값은 수집 시 누적되며 세션이 보강될 때 고정됩니다. 그 이후에 도착하는 이벤트는 값을 변경하지 않습니다.
Judge 비용은 구조적으로 별개입니다. [Agent] Evaluator Enrichment Cost USD은(는) 사용자가 정의한 평가자를 위한 [Agent] Evaluator Result 이벤트에 나타나며 세션 비용 USD에 포함될 수 없습니다. Amplitude의 내장 신호 비용은 어디에도 보고되지 않으며, 제품에 포함되어 있습니다.
모든 것이 USD로 이루어지며, 어디에도 통화 전환이 없습니다. 공급업체의 청구서를 재무적 진실의 소스(financial source of truth)로 취급하십시오. 많이 캐시되거나 배치 할인된 워크로드는 다를 수 있습니다. 에이전트 분석(Agent Analytics) 비용 데이터는 청구서에서는 확인할 수 없는 분석 뷰로, 에이전트별, 사용자별, 주제별 어트리뷰션을 제공합니다.
관리형 스키마
[Agent] 택소노미는 Amplitude에서 관리하며, 데이터 카탈로그의 속성 이름, 유형 및 등록은 자동으로 처리됩니다. 고유한 차원을 추가하려면 [Agent] Context (SDK 이벤트에 존재하며 세션 레코드에 에코된 JSON 속성)을 사용하거나 도구에서 표준 제품 이벤트를 발생시킵니다. 차트에서 쿼리할 수 없을 수 있으므로 등록되지 않은 플랫 속성을 [Agent] 이벤트에 추가하지 마십시오.
이 내용이 도움이 되었나요?
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.