AI SDK 없이 에이전트 이벤트 전송

AI SDK 없이 [Agent] 이벤트를 직접 발생시키거나 track() 표준 Amplitude SDK를 사용하거나 HTTP API로 POST를 전송하여 Agent 분석 데이터를 전송할 수 있습니다. Amplitude는 SDK에서 생성된 이벤트와 동일한 방식으로 세션을 구축하고 이러한 이벤트에 대해 보강을 실행합니다.

AI SDK가 런타임에 맞지 않을 때 이 경로를 사용하십시오. AI SDK는 Node.js와 Python만 지원하므로 일반적인 경우 브라우저와 클라이언트-중심 SPA, Cloudflare Workers 및 Deno와 같은 에지 런타임, Java, Go, Ruby와 같은 언어가 있습니다. 또한 Lovable, Superblocks, v0 또는 Bolt와 같은 AI 앱 빌더도 다루는데, 이 경우 생성된 앱은 브라우저 우선 방식이므로 Node 전용 모듈을 @amplitude/ai 가져오려고 하면 실패합니다. AI SDK를 실행할 수 있는 경우 대신 사용하십시오. 이 SDK는 세션 생애주기 분석, 민감 정보 제거 및 ID를 대신 처리합니다.

SDK가 없으면 세 가지 작업이 코드로 이동합니다.

  • 세션 생애주기 분석: 작업 단위가 완료되면 [Agent] Session End을(를) 전송합니다. 선택 사항이며 권장됩니다. 이 항목을 생략하면 Amplitude는 기본적으로 30분 동안 유휴 상태가 지속되면 세션을 종료합니다.
  • 개인정보 보호: track()을(를) 호출하기 전에 콘텐츠를 편집합니다.
  • ID 규칙: 세션, 턴, 추적 및 에이전트 ID를 생성하고 연결합니다.

최소 이벤트 전송

모든 세션에 대해 다음 이벤트를 발생시킵니다:

  1. [Agent] User Message
  2. [Agent] Tool Call, 호출당 하나, 에이전트가 도구를 사용할 때만
  3. [Agent] AI Response
  4. [Agent] Session End, 선택 사항이자 권장 사항이며, 작업 단위가 완료될 때 하나를 생성합니다

와이어 형식은 [Agent] 이벤트 규약이 JSON으로 구성된 Amplitude HTTP 엔드포인트로의 POST 요청입니다:

bash
curl -X POST https://api2.amplitude.com/2/httpapi \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "events": [{
      "event_type": "[Agent] User Message",
      "user_id": "user-123",
      "event_properties": {
        "[Agent] Session ID": "ticket-42",
        "[Agent] Turn ID": 1,
        "[Agent] Trace ID": "trace-abc",
        "[Agent] Agent ID": "support-bot",
        "[Agent] Message ID": "msg-1",
        "$llm_message": { "text": "I need a refund" }
      }
    }]
  }'

EU 데이터 레지던시의 경우 https://api.eu.amplitude.com/2/httpapi을(를) 사용하세요. 이 페이지의 나머지 부분은 표준 SDK track() 경로와 원시 HTTP 경로 모두에 적용됩니다.

또한 모든 이벤트에는 공유 속성([Agent] Session ID, [Agent] Turn ID, [Agent] Trace ID, [Agent] Agent ID, [Agent] Env, 및 [Agent] Runtime)과 해당 이벤트 유형에 필요한 속성이 Plus 포함됩니다. 프로덕트 분석에 사용하는 것과 동일한 사용자 ID를 전송하고, 각 이벤트에 고유한 insert_id을(를) 설정하여 재시도 시 중복이 발생하지 않도록 하십시오. 각 이벤트의 필수 속성에 대해서는 택소노미의 이벤트 계약을 참조하십시오.

항상 [Agent] Agent ID을(를) 설정하십시오. 이 정보가 없으면 Amplitude는 이벤트를 수락하지만 세션으로 그룹화할 수 없으므로 Agent 분석 뷰에서 제외됩니다. HTTP API는 Agent 분석이 이벤트를 처리하기 전에 수신을 확인하기 때문에 여전히 200를 반환하므로 200가 올바른 그룹화를 확인하지 않습니다.

세션이 실행된 A/B 테스트 또는 기능 플래그 변형을 기록하려면 모든 이벤트에 [Agent] Experiments을(를) key:variant 문자열 배열(예: ["planner:v2"])로 추가하십시오. 정확히 하나의 실험이 적용되는 경우 [Agent] Experiment Key , [Agent] Experiment Variant 및 [Agent] Experiment Unit (agent_session , turn 또는 span)도 설정합니다. Agent 분석에서 실험 변형 기록을 참조하십시오.

사용자 평가를 [Agent] Score이벤트로 전송하려면 AI SDK 없이 피드백 보내기를 참조하십시오.

규칙 수동 계측이 잘못 수행된 경우

  • $llm_message은(는) 객체입니다: { text: "..." }을(를) 보내십시오. Amplitude는 오류가 없는 일반 문자열을 무시하며, 스레드 뷰에는 메시지 콘텐츠가 표시되지 않습니다.
  • Turn ID는 이벤트가 아닌 교환을 식별합니다: 사용자 메시지 왕복 시 Turn ID를 1회 증가시키고, 해당 교환의 사용자 메시지, 모든 도구 호출 및 AI 응답에 동일한 값을 표시하십시오. 한 턴 내 순서는 이벤트 시간에 따라 결정되므로, 실제 실행 순서에 맞춰 AI 응답 전에 도구 호출을 발생시키십시오. 라운드 트립당 [Agent] Trace ID 한 개를 생성하고 동일한 이벤트 간에 공유합니다.
  • 택소노미를 준수하십시오: 등록되지 않은 이벤트 유형이나 속성은 차트에서 쿼리할 수 없을 수 있으므로 [Agent] 접두사 아래에 임의로 만들지 마십시오. 에이전트가 수행하는 구매, 예약, 추천 클릭과 같은 비즈니스 작업의 경우, 기존 이름과 동일한 user_id을(를) 사용하여 표준 제품 이벤트를 발생시키십시오. 이를 통해 에이전트 주도 여정과 클릭 주도 여정을 하나의 퍼널에서 비교할 수 있습니다.
  • 직접 비용을 제공하십시오: Amplitude는 모델 및 토큰 속성에서 [Agent] Cost USD를 계산하지 않으므로 비용 보고를 원할 때 포함하십시오. 비용 계산 방법을 참조하십시오.
  • 토큰 및 비용 속성은 AI 응답에만 존재합니다. 도구 호출은 토큰을 소비하지 않습니다. 서버는 수집하는 모든 이벤트에서 [Agent] Cost USD을(를) 합산하므로 도구 호출 또는 세션 종료에 대한 비용은 세션 합계를 증가시킵니다.
  • 사용자 간에 세션 ID를 재사용하지 마십시오: 공유 세션 ID는 다른 사용자의 대화를 병합하고 사용자별 분석을 방해합니다.

세션 닫기

채팅 종료, 티켓 해결, 실행 완료 등 작업이 종료될 때 [Agent] Session End을(를) 방출합니다. 서버는 SDK에서 발생시킨 닫기 이벤트의 경우와 정확히 마찬가지로 해당 이벤트에 대해 세션을 닫습니다. 닫는 세션과 일치하는 [Agent] Session ID을(를) 포함하고 에이전트 분석(Agent Analytics)을 활성화한 프로젝트로 이벤트를 전송합니다.

json
{
  "event_type": "[Agent] Session End",
  "user_id": "user-123",
  "event_properties": {
    "[Agent] Session ID": "session-abc",
    "[Agent] Agent ID": "support-bot"
  }
}

Amplitude는 이벤트의 추가 속성을 저장하지만 닫히는 데 영향을 주지 않습니다.

Session End를 전송하지 않으면 서버는 30분 동안 비활성 상태로 유지될 경우 세션을 닫습니다. 해당 시간 초과가 중단된 세션을 처리하도록 하십시오. 세션 종료의 작동 방식과 늦은 이벤트가 보강되지 않는 이유에 대해서는 How sessions close를 참조하십시오.

세션을 30분 이상 오래 열린 상태로 유지하려면 [Agent] Context에서 유휴 시간 초과 재정의를 설정합니다. 대신 짧은 유휴 타이머를 직접 구축하지 마십시오. 세션 ID를 순환하면 하나의 대화가 여러 세션으로 분할되기 때문입니다. 세션 시간 초과 구성을 참조하십시오.

추적하기 전에 콘텐츠를 마스킹하십시오.

마스킹은 track()전에 실행되어야 합니다. 가장 일반적인 실수는 메시지 콘텐츠를 게이팅하고 콘텐츠를 포함하는 다른 속성을 잊어버리는 것입니다. 개인정보 보호 모드를 네 가지 모두에 적용합니다:

  • [ $llm_message.text 사용자 메시지 및 AI 응답의 경우
  • [ [Agent] System Prompt AI 응답의 경우
  • [ [Agent] Tool Input 및 [Agent] Tool Output Tool Call의 경우 (페이로드는 객체이므로 재귀적으로 마스킹)
  • [ [Agent] Comment 점수 기준

metadata_only 동작의 경우 4개 항목을 모두 생략합니다. 비용, 지연 시간, 토큰 및 세션 그룹화는 여전히 확인됩니다. full 동작의 경우 추적하기 전에 PII(이메일, 전화번호, SSN, 신용카드 번호, IP 주소)를 마스킹하십시오.

브라우저 및 Edge 노트

  • 식별: localStorage로 전송된 user_id의 영구 익명 UUID는 익명 방문자에게 안정적인 ID를 제공합니다. 표준 사용자 식별은 사용자가 로그인할 때 해당 ID들을 병합합니다.
  • 세션 리플레이: 세션 리플레이 플러그인이 활성화된 상태에서 모든 에이전트 이벤트에 리플레이 속성을 추가하여 세션이 기록과 연결되도록 합니다. 세션 리플레이 링크를 참조하십시오.
  • 전송: 비콘 전송을 전역으로 설정하지 마십시오. 예를 들어 세션 종료 핸들러 내에서 setTransport('beacon')을(를) 호출하는 것은 전체 SDK에 영구적으로 적용되므로 이후 모든 이벤트는 재시도 없이 한 번 전송되며 오류 없이 드롭될 수 있습니다. 기본 전송을 사용합니다.
  • 대기 시간(Latency) 및 토큰: 이를 서버 측에서 측정하고, 응답과 함께 클라이언트로 반환한 다음 이벤트에 첨부하십시오.

AI 앱 빌더 내에서 계측(Instrument)하십시오.

Lovable, Superblocks 또는 모든 프롬프트 기반 빌더에서 이 프롬프트를 빌더의 에이전트에 붙여넣고 생성된 결과를 검토하십시오.

text
Instrument this app's chat agent with Amplitude Agent Analytics using the standard
@amplitude/analytics-browser SDK (do NOT use @amplitude/ai, it is Node-only and will
crash this runtime). Emit these events via amplitude.track(): [Agent] User Message at
request start, one [Agent] Tool Call per tool invocation in execution order,
[Agent] AI Response after the reply, and [Agent] Session End when the chat genuinely ends
(no short idle timers; the server auto-closes idle sessions). On every event include
[Agent] Session ID (one stable UUID per conversation), [Agent] Turn ID (increment once
per user-message exchange and stamp the same value on all events of that exchange),
[Agent] Trace ID (new UUID per exchange), [Agent] Agent ID (a stable name for this agent),
and [Agent] Runtime: "browser". Message text goes in $llm_message as { text: "..." }
(an object, not a string) on User Message and AI Response only. Put [Agent] Model Name,
[Agent] Provider, token counts, [Agent] Latency Ms, and [Agent] System Prompt on AI
Response only. Put [Agent] Tool Name, [Agent] Tool Success, [Agent] Latency Ms,
[Agent] Invocation ID, and [Agent] Parent Message ID on Tool Call. Redact PII (emails,
phones, SSNs, cards, IPs) from all message text, system prompts, and tool payloads
before tracking. Use one persistent anonymous UUID from localStorage as the Amplitude
user_id. Never call setTransport("beacon"). Use functional state updates when computing
turn counters from UI state so follow-up messages aren't lost to stale closures.

그런 다음 메시지 두 개(그중 하나는 도구를 트리거함)를 전송하고 라이브 이벤트에서 다음을 확인합니다:

  1. 모든 이벤트는 하나의 세션 ID를 공유합니다.
  2. 각 교환은 하나의 Turn ID와 하나의 Trace ID를 공유합니다.
  3. 도구 호출은 해당 AI Response보다 먼저 발생합니다.
  4. $llm_message.text은(는) 세션 스레드 뷰에 나타납니다.

이 내용이 도움이 되었나요?

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.

이 페이지에서