데이터 웨어하우스에서 에이전트 대화 가져오기

웨어하우스 가져오기는 Snowflake, BigQuery 또는 Databricks에 이미 저장된 에이전트 대화를 [Agent] 이벤트로 전환하며, AI SDK나 포워더 작업이 필요하지 않습니다. 테이블을 표준 모양에 매핑하는 SQL 쿼리 하나를 작성하면, 설정한 일정에 따라 Amplitude 웨어하우스 가져오기가 실행됩니다. OpenTelemetry, OpenInference 또는 MLflow 스팬으로 저장된 대화는 Amplitude의 OTLP 엔드포인트로 재생되는 별도의 경로를 사용합니다.

기록을 포함하여 이미 웨어하우스에 저장된 대화에는 웨어하우스 가져오기를 사용하십시오. 여전히 구축 중인 에이전트라면 대신 AI SDK 또는 OpenTelemetry로 계측하십시오. 이를 사용하면 실행되는 내용을 더 자세히 캡처할 수 있습니다.

AI 코딩 에이전트로 설정(권장)

이 프롬프트를 Cursor, Claude Code, Windsurf, GitHub Copilot 또는 Codex와 같은 AI 코딩 에이전트에 붙여넣으십시오. 에이전트는 가이드를 가져와 작업을 빌드한 다음, 모의 실행으로 시작합니다.

text
Connect the agent conversations in our warehouse to Amplitude Agent Analytics.
Fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/warehouses/README.md
If @amplitude/ai is installed, the same file is under node_modules/@amplitude/ai/docs/integrations/.
Follow links in the guide. If your source isn't listed, start at https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/README.md
Follow "Part 2: Coding agent procedure". Start with a dry run.

에이전트는 중단하고 사용자 ID를 포함하는 필드와 같이 추론할 수 없는 값을 묻습니다. 변경 사항을 검토한 다음 시작하기의 단계에 따라 확인합니다.

이것이 여러분에게 의미하는 바

  • 다음과 같이 작성합니다: 테이블에서 표준 열로 매핑하는 Stage 1이라는 하나의 매핑 쿼리. 공유된 두 번째 쿼리인 Stage 2는 이러한 열을 [Agent] 이벤트로 변환합니다. Stage 2를 편집하지 마십시오.
  • Amplitude 실행: 일정(보통 매시간)에 따라 가져오기 실행. 쿼리를 수동으로 다시 실행하지 않습니다.
  • 사용자의 웨어하우스 실행: 쿼리 자체는 웨어하우스 컴퓨팅 리소스에서 실행됩니다. Databricks에서는 이벤트 테이블을 최신 상태로 유지하는 MERGE 작업도 예약할 수 있습니다.

지원되는 소스 형식

테이블에서 대화를 저장하는 방식에 맞는 가이드를 선택하세요:

공유 열, 설정 및 웨어하우스별 설정을 설명하는 웨어하우스 가져오기 요약부터 시작하십시오.

웨어하우스 요구 사항

  • Snowflake: Amplitude의 Snowflake 소스로, 이벤트 데이터 유형이며 import_cursor 열을 기준으로 타임스탬프 기반 동기화가 적용됩니다. 타임스탬프를 UTC로 저장합니다.
  • BigQuery: Amplitude의 BigQuery 소스로, 이벤트 데이터 유형이며 import_cursor 열을 기준으로 시간 기반 동기화가 적용됩니다.
  • Databricks: Amplitude의 Databricks import는 Delta 테이블의 변경 데이터 피드를 읽으며 뷰를 읽을 수 없습니다. 변경 데이터 피드가 켜진 상태로 이벤트 테이블을 생성한 다음 쿼리의 출력을 해당 테이블에 기록하는 MERGE작업을 예약합니다.

또한 프로덕트 분석에서 사용자 ID와 일치하는 사용자 ID 열도 필요합니다. Amplitude는 대화 ID, 사용자 또는 장치 ID 또는 에이전트 ID 없이 행을 삭제합니다.

계승되는 항목

웨어하우스 가져오기는 테이블에 기록된 내용만 전송합니다. 모델, 토큰, 비용 및 도구 호출은 테이블에 해당 항목이 있을 때 표시되며, 그렇지 않은 경우에는 비어 있습니다. Amplitude는 누락된 값을 추정하지 않습니다. 각 대화는 [Agent] Session End 하나를 받으므로, 대화가 정착되면 내장 신호가 실행됩니다. 선택적 experiment_key 및 experiment_variant 열은 단위 agent_session가 있는 [Agent] Experiment* 속성이 되며, 행당 하나의 실험이 포함됩니다. 유효하지 않은 키나 변형이 있는 행은 해당 항목 없이 가져옵니다. 에이전트 분석에서 실험 변형 기록을 참조하십시오. 필드를 생략하거나 편집하려면 데이터가 웨어하우스를 떠나기 전인 1단계에서 수행하십시오. 패턴 목록 및 메타데이터 전용 선택 항목은 에이전트 분석 개인정보 보호 모드에 있습니다.

최신성 및 제한

  • 안정화 시간: 대화가 유휴 상태인 후 가져오기가 settle_hours 수행되며, 기본값은 2입니다. 대화 중 가장 긴 실제 일시 중지 시간보다 길게 설정하십시오.
  • 업데이트: 가져오기는 새 행과 updated_at이(가) 더 최신인 행을 반영합니다. 가져오기 후 재개되는 대화는 첫 번째 세션 종료를 유지합니다.
  • 중복: Amplitude는 7일 내에 반복 이벤트를 중복으로 제거합니다. 이보다 오래된 행을 다시 가져오면 중복이 생성됩니다.
  • 백필(Backfill): 첫 번째 동기화는 쿼리가 반환하는 모든 완료된 대화를 가져옵니다. 먼저 일주일을 가져오고 확인한 다음 쿼리가 얼마나 뒤로 표시되는지 넓히십시오.

저장된 스팬(span) 다시 실행

OpenTelemetry, OpenInference 또는 MLflow 스팬의 경우 웨어하우스에서 스팬을 내보내고 otlp-replay.mjs을(를) 사용하여 다시 실행하십시오. 이 설치는 앱에 SDK를 추가하지 않습니다:

bash
npm install --no-save --ignore-scripts @amplitude/ai
node node_modules/@amplitude/ai/docs/integrations/warehouses/otlp-replay.mjs

이 스크립트는 Node.js 18 이상과 Amplitude 프로젝트 API 키가 필요하며, 스팬을 Amplitude의 OTLP 엔드포인트(US 또는 EU)로 전송합니다. 내보내기 및 재생을 예약합니다(예: 시간별). 전송하지 않고 미리 보려면 --dry-run을(를) 사용합니다.

스팬에 대화 ID가 없으면 각 추적은 자체 세션이 됩니다. Amplitude는 해당 기간 내에서만 중복 제거를 수행하므로 7일이 넘은 기간은 다시 실행하지 마십시오.

시작하기

  1. 지원되는 소스 형식에서 해당 형식에 대한 가이드를 엽니다.
  2. Stage 1을 작성하십시오. 이 설치는 앱에 SDK를 추가하지 않습니다: npm install --no-save --ignore-scripts @amplitude/ai, 그 후 node node_modules/@amplitude/ai/docs/integrations/check-agent-events.mjs을(를) 사용하여 샘플을 확인하십시오.
  3. Amplitude에서 웨어하우스 소스를 생성하고 1주일 분량의 데이터에 대해 첫 번째 동기화를 실행합니다.
  4. 라이브 이벤트와 세션 뷰어를 확인한 다음 두 번째 동기화를 실행하여 중복 항목이 추가되지 않는지 확인하십시오.

가이드는 2026년 10월 6일에 마지막으로 확인되었습니다.

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

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.

이 페이지에서