에이전트 분석 세션 및 사용자 ID
에이전트 세션은 에이전트가 사용자를 위해 수행하는 하나의 작업 단위로, 시작 단계, 일련의 턴 및 결과(티켓 해결, 작업 완료, 대화 종료)를 포함합니다. 에이전트 분석은 해당 결과를 생성한 모든 이벤트를 하나의 [Agent] Session ID(으)로 그룹화하며, 세션이 종료된 후 세션에 대해 보강을 실행합니다. [Agent] Session End은(는) 선택 사항이며 권장됩니다. 이를 전송하는 것이 명시적 종료입니다. 절대로 도착하지 않는 경우, Amplitude는 아래의 생애주기 분석 규칙에 따라 세션을 닫습니다. 롤아웃 후 두 가지 모두를 변경하기 어렵기 때문에 계측하기 전에 세션 ID와 사용자 ID를 결정하십시오.
세션이란
세션은 하나의 결과(User Message, AI Response, Tool Call, Score, Span)를 생성한 이벤트를 하나의 [Agent] Session ID로 그룹화합니다. 세션은 코드가 해당 ID에 이벤트를 처음 첨부할 때 시작되며, 활동이 계속 들어오는 동안 열린 상태로 유지되다가, 명시적으로 또는 유휴 타임아웃에 의해 닫힙니다. 인리치먼트(세션 레코드, 신호, 평가자 결과)는 세션이 종료된 후, 세션당 한 번씩 실행됩니다.
모든 세션은 사용자에게 속합니다. 프로덕트 분석에 사용하는 것과 동일한 사용자 ID를 전달합니다. 사용자 ID 설정을 참조하십시오.
에이전트 세션 대 표준 분석 세션:
에이전트 세션은 Amplitude의 표준 분석 세션과 다릅니다. 에이전트 세션인 [Agent] Session ID은(는) 사용자가 에이전트에게 전달하는 작업 중 하나이며, 애플리케이션이 해당 ID를 소유합니다. Amplitude의 표준 분석 세션은 세션 리플레이 및 제품 보고서를 지원하는 사용자의 앱 또는 웹 방문입니다.$session_id 한 번의 방문에 여러 에이전트 세션이 포함될 수 있습니다. 두 세션을 연결하려면 에이전트 세션을 세션 리플레이에 연결을 참조하십시오.
세션 ID 선택
애플리케이션에서 이미 가지고 있는 "이 작업 단위"에 대해 ID를 전달합니다.
| 에이전트 유형 | 사용할 세션 ID |
|---|---|
| Chatbot 또는 copilot | 스레드 또는 대화 ID |
| 지원 에이전트 | 티켓 ID |
| Coding agent | 작업 또는 티켓 ID |
| 음성 에이전트 | 통화 ID |
| 백그라운드 또는 자율 에이전트 | 실행 또는 작업 ID |
아무것도 맞지 않는 경우, 세션이 시작될 때 안정적인 UUID를 생성하고 티켓 행, 스레드 레코드 또는 요청 컨텍스트와 같이 앱이 이미 작업 단위 상태를 유지하는 곳마다 이를 유지하십시오. 모든 요청 핸들러에서 동일한 ID를 스레딩하면 턴이 하나의 세션 내에 유지되므로, 요청당 새로운 ID를 생성하지 마십시오.
동일한 사용자가 새로운 목표를 가지고 돌아오면 새 ID로 새 세션을 시작하십시오. 사용자 간에 세션 ID를 재사용하지 마십시오. 공유 또는 글로벌 세션 ID는 서로 다른 사용자의 대화를 병합하고 사용자별 분석을 방해합니다.
세션 닫는 방법
Enrichment는 폐쇄된 세션에서만 실행됩니다. [Agent] Session Record이벤트가 나타나지 않는 경우 여기에서 시작하십시오.
세션은 다음 두 가지 방법 중 하나로 닫힙니다.
- Explicit close (권장): 코드가 작업 단위가 완료되면
[Agent] Session End를 전송합니다: 티켓 해결됨, 호출 종료됨, 실행 완료됨. AI SDK를 사용하여trackSessionEnd()(Node) 또는track_session_end()(Python)을 호출하거나, 범위가 종료될 때 세션을 닫는 범위 헬퍼를 사용하여 세션을 엽니다. Node에서는run(), Python에서는session()컨텍스트 관리자를 사용합니다. SDK가 없으면 직접 이벤트를 전송하십시오. 세션 닫기를 참조하십시오. Amplitude는 다음 수집 배치가 세션 종료 이벤트를 처리할 때 닫기를 기록하므로, 해당[Agent] Session Record이벤트는 일반적으로 15~20분 내에 도착합니다. 조직에 인리치먼트 백로그가 있는 경우 더 오래 걸릴 수 있습니다. - Idle timeout(자동 폴백): 명시적으로 닫지 않는 경우, 서버는 기본적으로 30분 동안 비활성 상태가 지속된 후 세션을 종료합니다. 사용자 메시지, AI 응답, 도구 호출, 세션 종료, 점수 및 스팬이라는 6개의
[Agent]이벤트 중 하나가 시계를 재설정합니다. 세션 레코드 및 평가자 결과(Evaluator Result)를 포함한 서버에서 생성된 인리치먼트 이벤트는 그렇지 않습니다. 수집은 주기로 실행되므로 유휴 기간이 경과한 후 약 15분 내에 세션이 종료됩니다.
모든 세션 레코드 [Agent] Close Reason에는 explicit_close 또는 timeout이(가) 포함되어 있으므로 유휴 시간 초과로 인해 세션이 닫히는 빈도를 모니터링할 수 있습니다.
닫으면 완료가 표시되며 세션이 잠기지는 않습니다. Amplitude는 여전히 이후 이벤트를 수락하고 저장하지만, 인리치먼트는 한 번만 실행되므로 지연된 이벤트는 세션의 신호, 롤업 또는 세션 레코드에 도달하지 않습니다. 최초 종료 이벤트만 카운트됩니다: Amplitude는 중복 항목을 무시하며, 유휴 시간 초과로 인해 세션이 이미 닫힌 후에 도착한 [Agent] Session End 이벤트도 무시합니다. 작업이 완료되면 닫습니다. 실제 작업이 계속되는 경우 새 세션을 시작하십시오.
유휴 시간 초과 값
세션별 재정의가 없는 세션도 활동에 관계없이 24시간 후에 닫힙니다. 재정의(양수 값 또는 -1)를 설정하면 세션이 해당 상한에서 제외됩니다.
| 값 | 행동 방식 |
|---|---|
30 | 기본값입니다. 30분 동안 비활성 상태가 지속되면 세션이 종료됩니다. |
240, 등. | 지원 티켓 및 코딩 에이전트와 같이 사람이 대기하는 작업의 시간 초과를 늘립니다. |
-1 | 유휴 기간은 90일이 되며 Amplitude는 24시간 제한을 포기하므로 명시적 세션 종료가 사실상 유일한 종료입니다. |
시간 초과를 너무 낮게 설정하면 긴 일시 중지로 인해 세션이 일찍 닫힙니다. Follow-up 이벤트는 여전히 첨부되고 Amplitude는 이를 저장하지만, 보강이 실행된 후 도착하므로 세션 기록에 도달하지 않습니다. 주말 동안 티켓이 유휴 상태이거나 장기간 실행되는 백그라운드 작업과 같이 조용한 기간이 정상적이고 무제한인 경우에는 -1을(를) 사용하십시오. 단점은 앱에서 닫는 것을 잊어버린 세션은 90일 백스톱이 닫힐 때까지 열린 상태로 유지되고 보강되지 않은 상태로 유지된다는 것입니다.
-1에 대한 두 가지 주의 사항:
- 보강이 비활성화된 에이전트는 조직 기본 일정에 따라 마감됩니다.
- 90일 제한은 세션이 시작된 시점부터 계산되므로 90일 이상 연속으로 활성 상태로 유지되는 세션은 자동 폐쇄되지 않습니다.
재정의를 설정하려면 세션 시간 초과 구성을 참조하십시오.
사용자 ID 설정
Amplitude는 세 가지 식별자(장치 ID, 사용자 ID 및 Amplitude ID)를 하나의 프로필로 결합하여 익명 세션, 로그인 및 여러 장치에서 고유 사용자를 계산합니다. 사용자가 인증을 받는 즉시 안정적인 사용자 ID를 전송하면 동일한 기기의 익명 이벤트가 하나의 프로필로 병합되고 활성 사용자(active-user) 수가 정확하게 유지됩니다.
모든 [Agent] 이벤트에 안정적인 사용자 ID가 포함되어 있으면 에이전트와 제품 동작에 걸쳐 퍼널, 코호트 및 리텐션 차트를 구축할 수 있습니다.
Amplitude가 다른 프로젝트에서 이미 사용자 ID와 연결되어 있는 알려진 장치 ID를 발견할 경우, Amplitude는 Portfolio 애드온이 없더라도 모든 프로젝트에서 장치 ID가 해당 사용자 ID와 연결되어 있다고 가정합니다. 자세한 내용은 포트폴리오를 참조하십시오.
두 가지 규칙은 단일 사용자가 두 사용자로 분할되는 것을 방지합니다:
- 절대로 위치 표시자 사용자 ID를 전달하지 마십시오. 자리 표시자에는 "anonymous", 빈 문자열 또는 임시 ID가 포함됩니다. 일단 설정된 사용자 ID는 변경할 수 없으므로 위치 표시자는 나중에 병합되지 않는 영구적 별도의 사용자를 생성합니다. 대신 사용자 ID를 생략합니다. 익명 활동은 사용자가 식별되면 표준 사용자 식별을 통해 알려진 ID에 병합됩니다.
- 사전 계정 세션에서 동일한 장치 ID를 재사용하십시오. 백엔드가 요청당 새 장치 ID를 생성하면 ID 병합이 중단됩니다. 가능한 경우 브라우저 SDK에서 장치 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.