에이전트 분석 계측 확인
라이브 이벤트에서 하나의 실제 상호 작용을 전송하고 생성하는 이벤트에 대해 9개의 게이트를 확인하여 계측을 확인하십시오. 게이트는 이벤트가 도착했음을 확인하고, 모델, 토큰, 비용 및 지연 시간을 전달하며, 실제 세션, 에이전트 및 사용자 ID를 사용하며, 개인정보 보호 모드가 전송할 때 메시지 콘텐츠를 포함합니다. 모든 경로를 사용하여 계측한 후 이 검사를 실행하고, 프로덕션 체크리스트를 사용하여 롤아웃하기 전에 다시 실행하십시오.
9개 게이트 확인
계측된 코드에서 하나의 실제 상호 작용을 전송하고 프로젝트의 라이브 이벤트 스트림을 연 다음, 다음 사항을 확인하십시오:
- 이벤트는 모두에게 도착합니다.
- 모델 이름과 공급자가 채워집니다.
- 토큰 수가 채워집니다.
- USD 비용이 채워집니다.
- 지연 시간이 채워집니다.
- 세션 ID는 실제 ID이며 자동 생성된 자리 표시자가 아닙니다.
- 에이전트 ID는 구성 요소별로 설정됩니다.
- 사용자 ID는 인증 계층에서 가져옵니다.
- 개인정보 보호 모드가 콘텐츠를 전송할 때 메시지 콘텐츠는 사용자 메시지에 표시됩니다.
AI 코딩 에이전트를 사용하여 계측한 경우, 계측의 일부로 검증 테스트를 작성합니다. Gates 6~8은 의도적으로 위치 표시자 ID에 실패하므로 롤아웃 전에 위치 표시자를 실제 ID로 교체하십시오.
Gate 9는 다른 곳에서 조용히 실패하는 항목입니다. SDK는 빈 메시지 문자열을 전송하는 대신 삭제하므로, 채워지지 않은 변수에 연결된 에이전트가 게이트 1~8을 통과해도 읽을 수 있는 데이터가 전달되지 않습니다. 스레드 보기는 비어 있는 상태로 유지되며, Amplitude는 콘텐츠 기반 신호에 점수를 매길 수 없습니다. 게이트는 의도적으로 콘텐츠를 제거하는 metadata_only 또는 customer_enriched에는 적용되지 않습니다.
OpenTelemetry의 경우 주요 검사는 게이트 6~8입니다. OpenTelemetry 페이지에서 확인을 참조하십시오.
배포하기 전에 AI SDK를 확인하십시오.
AI SDK를 사용하는 경우 doctor를 실행하여 환경 변수, 설치된 종속성 및 이벤트-파이프라인 연결을 확인하십시오:
npx -y -p @amplitude/ai amplitude-ai doctor
기본적으로 닥터는 AMPLITUDE_AI_API_KEY을(를) 읽습니다. 앱에서 키 이름을 다르게 지정할 경우 -key-env를 사용해 올바른 변수를 지정하십시오.
npx -y -p @amplitude/ai amplitude-ai doctor -key-env MY_KEY_NAME
값을 지정하지 않고 -key-env을(를) 전달하면 Doctor는 기본값으로 돌아가는 대신 사용 메시지와 함께 종료됩니다.
summary()을(를) 사용하여 충전율 리포트를 가져오십시오.
배포하기 전에 MockAmplitudeAI.summary()을 사용하여 캡처된 모든 이벤트에 대한 채우기 리포트를 얻습니다. 데이터가 Amplitude에 도달하기 전에 검증 게이트를 확인하고 격차를 플래그합니다.
import { AIConfig } from "@amplitude/ai";
import { MockAmplitudeAI } from "@amplitude/ai/testing";
const mock = new MockAmplitudeAI(new AIConfig({ contentMode: "full" }));
const agent = mock.agent("test-agent", { userId: "u1" });
await agent.session({ sessionId: "s1" }).run(async (s) => {
s.trackUserMessage("hello");
s.trackAiMessage("response", "gpt-4o-mini", "openai", 150);
});
console.log(mock.summary());
요약 결과는 다음과 같습니다.
Agent Analytics fill-rate report
================================
Events captured: 2
[Agent] User Message: 1
[Agent] AI Response: 1
Verification gates (8/8 passing):
✓ user_id or device_id present
✓ [Agent] Session ID present
✓ [Agent] Agent ID present
✓ [Agent] Model Name present
✓ [Agent] Provider present
✓ [Agent] Latency Ms > 0
✓ [Agent] Input Tokens > 0
✓ [Agent] Output Tokens > 0
✓ [Agent] Cost USD > 0
CI에서 이러한 검사를 유지하려면 모의 클라이언트를 사용하여 이벤트에 대해 어설트하십시오. SDK 참조에서 모의 클라이언트에 대한 테스트를 참조하십시오.
실패한 게이트 수정
| 게이트 실패 | 원인 | 수정 |
|---|---|---|
user_id 누락됨 | 세션에 전달된 userId 또는 deviceId이 없습니다 | 브라우저 SDK에서 agent.session() 에 userId 을 설정하거나 deviceId 을 전달하십시오 |
Session ID 누락됨 | ID 없이 세션이 생성됨 | 다음sessionId으로 전달 agent.session() |
Model / Provider | 지원되는 공급자 또는 사용자 지정 게이트웨이 없이 patch() 사용 | 모델과 공급자를 trackAiMessage()에 명시적으로 전달하거나 공급자 래퍼를 사용하십시오. |
Input/Output Tokens = 0 | 공급자가 스트리밍 모드에서 사용량을 반환하지 않음 | onFinish/ stream_options: { include_usage: true }를 사용하여 최종 토큰 수를 캡처합니다 |
Cost USD = 0 | 인식할 수 없는 모델 이름 | 정규 공급자 모델 ID를 사용하거나 totalCostUsd을(를) 명시적으로 설정하십시오. |
다른 증상은 에이전트 분석 설정 문제 해결을 참조하십시오.
프로덕션 체크리스트
이벤트가 Amplitude로 유입되기 시작하면 다음을 확인하십시오:
- 이벤트에는 실제 사용자 ID가 포함됩니다.
- 이벤트에는 실제 세션 ID가 포함됩니다.
- 결과가 알려진 곳에서는 세션을 명시적으로 닫으며, 예상된 경우에만 유휴 시간 초과에 의해 닫힙니다.
- 개인정보 보호 모드를 결정하고 검토했습니다.
- 에이전트 ID는 안정적이고 사람이 읽을 수 있으며, 위임을 위해 하위 에이전트를 구성했습니다.
이 내용이 도움이 되었나요?
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.