에이전트 분석 설정 문제 해결
대부분의 에이전트 분석 설정 문제는 세 가지 원인으로 발생합니다. 즉, 세션이 닫히지 않거나, 이벤트가 필수 ID를 누락하거나, 콘텐츠가 잘못된 형태로 전송됩니다. 아래에서 증상을 찾으십시오. 새로운 계측을 종단간으로 확인하려면 에이전트 분석 계측 확인을 참조하십시오.
세션 레코드 이벤트가 나타나지 않음
Amplitude는 세션이 종료된 후에만 enrichment를 실행하며 [Agent] Session Record를 기록합니다.
- 세션이 아직 닫히지 않았습니다: 명시적 종료 후 세션 레코드는 일반적으로 15~20분 내에 도착하며, 이후 Enrichment 백로그 중에 도착합니다. 명시적 종료가 없으면 세션은 유휴 시간 초과(기본값 30분) Plus 최대 약 15분 동안 수집을 기다립니다.
- 코드에서 세션 종료를 절대 전송하지 않음: 작업이 종료될 때 전송하거나 유휴 시간 초과를 기다리십시오. 세션 닫기 방법을 참조하십시오.
- 종료 이벤트는 프로세스를 떠나지 않습니다: AI SDK를 사용하면 프로세스가 다시 시작될 때 메모리에 버퍼링된 종료 이벤트가 손실됩니다. 장 마감 후
ai.flush()을(를) 호출하십시오. 세션 닫기 및 플러시를 참조하십시오. - 빈 세션 레코드: 최신 AI SDK로 업데이트합니다. 현재 릴리스 타임라인은 실제 활동에서만 세션을 생성합니다.
- Session End가 시간 초과 후 도착합니다: Amplitude는 유휴 시간 초과로 인해 이미 세션을 폐쇄한 후 도착하는 Session End를 무시합니다.
[Agent] Close Reason에서timeout의 비율이 높으면, 예를 들어 페이지를 닫을 때만 이벤트가 실행되는 등 작업이 너무 늦게 발생할 수 있습니다. - 레코드에서 마지막 턴이 누락되었습니다: 각 세션은 하나의 세션 레코드를 가집니다. Amplitude는 세션 종료 후 도착하는 이벤트를 저장하지만 보강하지는 않습니다. 세션에 기록이 전혀 없고 마지막 활동이 시간 초과를 훨씬 지난 경우, 세션 ID를 사용하여 지원 팀에 문의하십시오.
이벤트 없음
- LLM 호출이 세션 외부에서 실행됩니다(AI SDK): SDK는 패치된 호출을 활성 세션 컨텍스트 외부에서 오류 없이 삭제하며, LLM 호출 자체는 여전히 성공합니다. 여기에는 스타트업 시 패치를 적용하지만 세션을 열지 않는 항목, 그리고 요청 범위를 벗어나는 백그라운드 작업, 워밍업 호출 및 Promise가 포함됩니다
AMPLITUDE_AI_AUTO_PATCH=true.session.run()(으)로 호출을 감싸거나, 미들웨어를 사용하거나,patch()을(를) 참조하십시오. - 이벤트는 프로세스를 떠나지 않습니다: SDK는 이벤트를 버퍼링합니다. 종료 시 또는 서버리스 함수 및 수명이 짧은 프로세스에서 호출할 때마다
flush()을(를) 호출하십시오. - 잘못된 프로젝트: API 키가 Agent 분석을 활성화한 프로젝트에 속해 있는지 확인하고 해당 프로젝트의 라이브 이벤트를 확인하십시오.
- 계측인지 전달인지 확실하지 않습니다:
debug: true(으)로 클라이언트를 구성하여 모든 추적된 이벤트를 stderr에 인쇄합니다. 아무것도 인쇄되지 않는 경우 세션 컨텍스트를 확인하십시오. 이벤트가 출력되지만 1분 내에 도착하지 않는 경우flush(), API 키와 프로젝트를 확인하십시오. node:async_hooksCloudflare Workers의 오류: 전체 AI SDK를 Worker에 번들로 포함할 수 없습니다. Edge 런타임과 Cloudflare Workers에서 fetch 기반 전송을 사용하거나 AI SDK 없이 이벤트를 전송합니다.
이벤트는 200을 반환하지만 세션으로 생성되지 않습니다.
이벤트가 누락되었습니다[Agent] Agent ID. HTTP API는 Agent 분석이 이벤트를 처리하기 전에 수신을 확인하므로, 이벤트가 올바르게 속성화되었다는 200의미는 아닙니다. HTTP API로 전송할 때 ai.agent()에 에이전트 ID를 설정하거나, 모든 이벤트에 [Agent] Agent ID을(를) 포함하십시오.
하나의 대화가 여러 세션으로 표시
- 요청당 새 에이전트: 요청 핸들러 내부에서
ai.agent(...)에이전트를 구성하면 매 턴마다 새로운 에이전트 ID가 생성됩니다. 모듈 범위에서 에이전트를 정의합니다. 오래 지속되는 서버에 에이전트와 세션 배치를 참조하십시오. - 요청당 또는 클라이언트 유휴 타이머 후에 새 세션 ID를 지정합니다: 작업의 각 턴에 하나의 안정적 세션 ID를 유지하십시오. 세션 ID 선택을 참조하십시오.
- 모든 OpenTelemetry 추적은 자체 세션이 됩니다.
gen_ai.conversation.id와 같은 대화 속성을 설정합니다. 이 ID가 없으면 Amplitude는 추적 ID로 되돌리고 세션을 성능 저하 상태로 표시합니다. 세션 및 사용자 속성 설정을 참조하십시오.
작업이 완료되기 전에 세션이 닫힙니다.
긴 일시 중지로 인해 유휴 시간이 초과되어, 보강 실행 후 도착한 이후 턴들이 Session Record에 도달하지 못했습니다. 자연적인 간격이 긴 작업의 시간 초과 설정을 늘리십시오. 세션 시간 초과 구성을 참조하십시오. 스트리밍된 응답이 세션보다 오래 지속되는 경우, 스트림이 소비될 때까지 세션을 열어 두십시오. 스트림 응답을 참조하십시오.
사용자는 unknown와 같이 표시되거나 두 개로 분할됩니다.
- OpenTelemetry 사용자
unknown: Amplitude가 판독하는 사용자 속성이 하나도 설정되지 않았습니다.enduser.id또는 다른 지원되는 속성으로 설정하십시오. - 한 사람은 두 명의 사용자로 표시됩니다. "anonymous"와 같은 자리 표시자 사용자 ID가 영구적으로 별도의 사용자를 생성하거나, 백엔드가 요청당 새 장치 ID를 생성했습니다. 사용자 ID 설정을 참조하십시오.
스레드 뷰에 메시지 콘텐츠가 표시되지 않습니다.
$llm_message은(는) 문자열입니다: 객체를 전송합니다.{ text: "..." }Amplitude는 오류를 발생시키지 않고 일반 문자열을 무시합니다.- 메시지 문자열이 비어 있습니다: AI SDK는 빈 메시지를 전송하는 대신 빈 메시지를 삭제합니다. 추적 시 전달하는 변수가 채워져 있는지 확인하십시오.
- 개인정보 보호 모드는 콘텐츠를 제거합니다:
metadata_only및customer_enriched은(는) 메시지 텍스트, 도구 입력 및 출력, 시스템 프롬프트, 예외 메시지 또는 스택 추적을 절대 전송하지 않습니다. 에이전트 분석 개인정보 보호 모드를 참조하십시오. - 텍스트가
[email]와 같은 자리 표시자로 대체됩니다: PII 편집이 활성화되었습니다. 편집(Redaction)은 이벤트가 프로세스를 떠나기 전에 일치하는 패턴을 대체합니다. - 스트리밍된 응답에는 텍스트가 없습니다: SDK가 응답을 기록하기 전에 스트림을 비우십시오.
비용이 누락되었거나, 0 또는 너무 높음
- AI SDK,
[Agent] Cost USD이(가) 누락되었거나$0: 모델 이름이 과금 체계에 없거나 미세 조정된ft:모델입니다. 정규 공급자 모델 ID를 사용하거나totalCostUsd값을 명시적으로 설정하십시오. 이전 SDK 릴리스는$0을(를) 기록하며, 현재 릴리스는 이 속성을 생략합니다. - HTTP API 또는 OpenTelemetry, 비용이 누락됩니다: Amplitude는 직접 이벤트에 대한 비용을 계산하지 않습니다.
[Agent] Cost USD또는gen_ai.usage.cost을(를) 보냅니다. - 세션 비용 USD가 누락됨: 세션에서 토큰 사용량이 있는 이벤트에 비용이 없는 경우, Amplitude는 부분 값을 보고하는 대신 세션 합계를 생략합니다. 일반적인 원인은 비표준 이름,
openrouter/auto와 같은 게이트웨이 별칭, 또는 미세조정된ft:모델과 같이 SDK에서 가격을 책정할 수 없는 모델입니다. 모델 ID를 수정하거나 해당 호출에 비용을 전달합니다. 이후 세션에는 합계가 표시됩니다. - 세션 비용이 너무 높습니다: 서버는 모든 이벤트의 합계를 처리하므로 도구 호출(Tool Call) 또는 세션 종료(Session End)에 대한 비용은
[Agent] Cost USD총액을 증가시킵니다. AI Response에만 비용을 입력하십시오. - Anthropic 캐시 토큰이 일치하지 않습니다:
inputTokens에cache_read_input_tokens및cache_creation_input_tokens을(를) 추가하십시오. 비용 및 토큰 관리를 참조하십시오.
비용 작동 방식에 대해서는 비용 계산 방법을 참조하십시오.
설정 초기에 확인이 실패합니다.
예상됨. 검증 게이트는 구성 요소별로 실제 사용자 ID, 실제 세션 ID 및 에이전트 ID를 포함한 전체 계측을 확인합니다. 플레이스홀더 ID나 최소한의 설정을 사용하면 ID 게이트가 남은 내용을 표시하지 않습니다. 에이전트 분석 계측 확인을 참조하십시오.
신호 결과가 누락되었거나 정보가 없어 보입니다.
- Amplitude에 도달한 콘텐츠가 없습니다:
metadata_only또는customer_enriched모드에서, 또는 계측기가 빈 문자열을 전송할 때, 콘텐츠 기반 신호가 읽을 데이터가 없습니다. Amplitude는 추측하는 대신 설정되지 않은 상태로 두므로, 실패한 것이 아니라 부재로 표시됩니다. Data Quality Issues는 여전히 실행되며, 비용, 지연 시간 및 오류 지표도 여전히 작동합니다. 콘텐츠를 전송하지 않고 품질을 측정하려면 직접 계산하고 세션 보강을 전송하십시오. - 세션이 작업 중간에 종료됨: 시간 초과에 도달한 절반의 세션은 불완전한 대화로 표시됩니다. 유휴 시간 초과를 수정한 다음 신호 품질을 다시 판단하십시오.
각 신호가 측정하는 내용에 대해서는 Agent Analytics 내장 신호를 참조하십시오.
[Agent] Topic Classification도착이 중단되었습니다.
Amplitude는 더 이상 이를 전송하지 않습니다. 주제 및 분류 결과는 세션 레코드에 [Agent] Evaluator Result(분류 출력)에 표시되고 [Agent] Topic Summary에 표시됩니다. 이전 이벤트에 구축된 차트를 해당 속성으로 이동합니다.
속성이 속하지 않는 이벤트에 나타납니다.
SDK는 AI Response 및 Embedding 이벤트에만 [Agent] Provider및 [Agent] Temperature를 작성합니다. Tool Call 또는 사용자 메시지 이벤트에 나타나면 이는 종종 ToolCallTracker.setAmplitude({ eventProperties })을(를) 통해 설정된 프로세스 전체 기본값인 eventProperties에서 가져옵니다. eventProperties(으)로 전달한 값을 감사하고 사용자 지정 세그멘테이션 차원에 context을(를) 사용하십시오.
실험 속성이 누락되었습니다.
이벤트에 [Agent] Experiments 또는 [Agent] Experiment Variant이(가) 포함되지 않는 경우 다음 원인을 확인하십시오.
- SDK 버전:
experiments이 옵션을 사용하려면 0.24.1 이상의 Node@amplitude/ai릴리즈 또는 1.20.1 이상의 Pythonamplitude-ai릴리즈가 필요합니다. - 삭제된 항목: SDK는 키 또는 변형이 비어 있거나, 256자를 초과하거나,
:를 포함하는 키를 포함하는 항목을 삭제하고 디버그 수준에서 기록합니다. 디버그 로깅을 켜서 찾습니다. - 배열만 해당: 두 개 이상의 실험에서 이벤트는
[Agent] Experiments을(를) 전달하지만 단일 실험 속성은 전달하지 않습니다. 대신[Agent] Experiments(으)로 속성화하십시오. - Forwarder 및 OpenTelemetry: Forwarder는 대화 기록에 포함된 경우에만 실험을 전송하며, OpenTelemetry 리시버는 GenAI 스팬에 대해
feature_flag.*속성과 스팬 이벤트만 읽습니다.
규칙에 대해서는 에이전트 분석의 실험 변형 기록을 참조하십시오.
Tool 호출에 0ms 지연 시간이 표시됨
patch() 는 메시지 배열에서 도구 호출을 추출했으므로 타이밍이 없습니다. 실제 지연 시간에 대해 tool()또는 trackToolCall()을 사용하십시오. Track 도구를 참조하십시오.
브라우저 이벤트가 오류 없이 드롭됩니다.
setTransport('beacon') 전체 SDK에 영구적으로 적용되므로 이후 모든 이벤트는 재시도 없이 한 번만 전송됩니다. 기본 전송을 사용합니다. Browser 및 Edge 노트를 참조하십시오.
OpenTelemetry Collector는 413을 얻거나 스팬을 삭제합니다.
413: 요청의 압축 해제된 크기가 4MB를 초과하거나 2,000개의 번역된 이벤트를 초과했습니다. Collector 배치 크기를 줄입니다.200(partial_success포함): 수집기가 일부 이벤트를 거부했으며,200이(가) Collector에게 배치를 삭제하도록 지시합니다.partial_successbody를 살펴보십시오.- 재시작 시 스팬 손실: 인메모리 대신 영구 전송 큐를 사용하십시오.
OpenTelemetry 수집 문서를 참조하십시오.
이 내용이 도움이 되었나요?
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.