에이전트 분석 택소노미

에이전트 분석은 관리형 이벤트 택소노미를 사용합니다. 모든 이벤트 이름과 속성에는 [Agent]이(가) 접두사로 붙으므로, 에이전트 데이터는 동일한 프로젝트 내에서도 제품 이벤트와 명확하게 분리되어 유지됩니다. 동일한 프로젝트와 동일한 사용자 ID를 공유하므로, 에이전트 및 제품 동작 전반에 걸쳐 차트를 만들고, 세그먼트를 분류하고, 코호트를 구축할 수 있습니다.

이 페이지는 에이전트 분석에서 생성하는 모든 이벤트 및 속성에 대한 참조입니다. 이벤트는 두 가지 프로듀서에서 제공됩니다.

  • SDK 계측은 에이전트가 실행되는 동안 실시간으로 이벤트를 발생시킵니다: 사용자 메시지, AI 응답, 도구 호출, Span, Embedding, 세션 종료, 세션 보강 및 점수.
  • Amplitude의 보강 파이프라인은 세션이 종료된 후 Session Record 및 Evaluator Result 이벤트를 발생시킵니다. Amplitude는 결코 점수 이벤트를 발생시키지 않습니다. 점수는 항상 애플리케이션에서 발생합니다.

데이터 계층 구조

에이전트 분석은 각 에이전트 상호 작용을 계층 구조로 모델링합니다.

에이전트는 모든 이벤트의 차원입니다: 모든 이벤트는 [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] Topic Classification은(는) 더 이상 발생하지 않습니다. 주제 및 분류 출력은 이제 [Agent] Evaluator Result(분류 유형)에 기록되며, 세션 레코드 내[Agent] Topic Summary에 표시됩니다. 주제 분류(Topic Classification)를 기반으로 차트를 구축한 경우 Evaluator Result로 마이그레이션하십시오.

신호: 품질이 보장되는 곳

Amplitude는 모든 종료된 세션에서 고정된 품질 신호 세트를 실행합니다. 신호 결과는 [Agent] Session Record 이벤트의 속성으로 표시되며, 세션당 하나의 레코드로 각 신호는 고유한 결과, 근거 및 (해당되는 경우) 증거 속성을 갖습니다. 신호는 별도의 이벤트를 생성하지 않습니다. 각 신호가 응답하는 내용과 해당 레이블이 의미하는 내용은 Agent Analytics 내장 신호를 참조하십시오.

신호 의미론에 대한 참고 사항:

  • 모든 신호는 근거를 작성합니다. 작업 완료됨, 응답 품질 및 데이터 품질도 증거를 작성할 수 있습니다. 신호는 방향성 지표이며 기본 사실이 아닙니다.
  • 작업 완료됨 및 응답 품질은 숫자 점수가 아닌 부울입니다. 트렌드를 확인하려면 값이 true인 세션의 비율을 차트로 표시합니다. Task Completed는 초기 오류 후 성공이 발생할 때 복구에 대해 크레딧을 부여하며 톤은 무시합니다. 응답 품질은 작업 결과와 무관하게 텍스트(정확하고, 명확하며, 구조화됨)를 판단합니다.
  • 부정적 피드백과 사용자 마찰은 연관되어 있지만 구별됩니다. 부정적 피드백은 사용자가 작성한 내용에 대한 명시적 불만족을 감지합니다. 사용자 마찰은 사용자가 불평을 하지 않더라도 재시도 폭풍과 설명 루프와 같은 행동 패턴을 감지합니다.
  • 앱이 전송하는 Thumb Down 또는 낮은 평가는 [Agent] Score부정적 피드백에 대한 명시적 불만족으로 간주됩니다. 사용자 피드백 수집을 참조하십시오.
  • 대부분의 신호에는 메시지 텍스트가 필요합니다. 세션에 metadata_only 및 customer_enriched와(과) 같이 아무것도 포함되지 않은 경우, 이러한 신호 속성은 실패로 보고되지 않고 세션 레코드에서 제외됩니다. 데이터 품질 보고는 여전히 활성화되어 있습니다. 각 모드가 전송하는 내용을 참조하십시오.

분류 값:

  • [Agent] User Intent: 정보 요청, 분석 및 합성, 작업 실행, 콘텐츠 생성, 조언 및 추천, 주제 외 / 소셜. 인사말이 아닌 세션 전반에 걸쳐 지배적 인텐트에 따라 분류됩니다.
  • [Agent] Session Safety: 일반(기본값), 주제외(Off-Topic), 프롬프트 삽입, 남용, Probing, 안전하지 않은 출력(에이전트가 유해한 콘텐츠를 생성함), 데이터 유출(에이전트가 PII, 자격 증명 또는 내부 정보를 노출함).

공통 속성

이들은 모든 또는 대부분의 SDK 이벤트에 나타납니다:

이벤트 계약

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을(를) 전송하여 재시도 시 중복이 발생하지 않도록 하십시오.

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] 으(로) 시작합니다.

이벤트 속성 참조

[에이전트] 사용자 메시지

[에이전트] AI 응답

[에이전트] 도구 호출

[Agent] Span 및 [Agent] Embedding

스팬에는 [Agent] Span Name, [Agent] Latency Ms, [Agent] Input State, [Agent] Output State, [Agent] Is Error, 선택적 상위 스팬 중첩 및 사용자가 첨부한 모든 속성이 포함됩니다. Embedding은 AI Response와 같이 모델, 공급자, 토큰 및 비용 속성을 포함합니다. Embedding 이벤트는 세션 파이프라인에 참여하지 않습니다. 즉, 유휴 시계를 재설정하지 않으며 해당 비용은 세션 비용 USD에 포함되지 않습니다.

[에이전트] 세션 종료

생애주기 분석 및 시간 초과 규칙에 대한 자세한 내용은 세션 닫기 방법을 참조하십시오.

[에이전트] 점수

애플리케이션의 피드백 이벤트입니다. Amplitude는 절대로 점수를 생성하지 않습니다. 프로젝트의 모든 Score는 코드에서 score() 또는 trackScore()을(를) 통해 제공됩니다.

[에이전트] 세션 보강

사용자 고유의 세션 수준 레이블: 품질 점수, 결과, 인프라에서 계산된 주제.trackSessionEnrichment() 또는 setEnrichments()을(를) 통해 전송됨. 모든 개인정보 보호 모드에서 작동하며, customer_enriched 모드의 기본 데이터 경로입니다.

[에이전트] 세션 기록

세션이 닫힌 후 세션당 한 번씩 발생합니다. 이는 품질 분석을 위한 핵심 이벤트입니다. 세션당 한 행에 모든 신호 결과 및 롤업이 포함됩니다. 세션당 정확히 하나의 세션 레코드가 있습니다.

세션 ID 및 롤업:

신호 결과(의미론은 위의 신호 표를 참조하십시오):

[Agent] Evaluator Result

닫힌 세션당 활성 사용자 지정 평가자당 한 번씩 발생합니다. 사용자 지정 평가자는 Amplitude UI에서 정의하고 조정하는 평가자이며, 내장 신호는 Evaluator Result 이벤트를 생성하지 않습니다.

평가자 ID 및 출력:

모든 평가자 결과에 복제되는 세션 차원으로, 세션 레코드에 조인하지 않고도 평가자 결과를 세그먼트화할 수 있습니다: [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.

이 페이지에서