Vercel AI SDK 추적을 Agent Analytics로 전송
Vercel AI SDK 7은 OpenTelemetry GenAI 스팬을 방출합니다@ai-sdk/otel. 해당 Exporter를 Amplitude로 지정하십시오. 에이전트 프로세스에서 Amplitude AI SDK는 필요하지 않습니다.
이 페이지에서는 ai 7.0.155와 @ai-sdk/otel 1.0.155, ai 6.0.317과 @ai-sdk/openai 2.0.138에 대해 설명합니다. Amplitude는 내보낸 스팬을 저장합니다. 개인 데이터가 인프라를 벗어나기 전에 스크럽하십시오. 에이전트 분석 개인정보 보호 모드를 참조하십시오.
AI 코딩 에이전트로 설정(권장)
이 프롬프트를 Cursor, Claude Code, Windsurf, GitHub Copilot 또는 Codex와 같은 AI 코딩 에이전트에 붙여넣으십시오.
Connect this Vercel AI SDK 7 app to Amplitude Agent Analytics with native OpenTelemetry.
Fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/vercel-ai-sdk.md
and follow "Part 2: Coding agent procedure".
If @amplitude/ai is installed, the same file is under node_modules/@amplitude/ai/docs/integrations/.
Also follow https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/privacy.md
and scrub content before export.
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
변경 사항을 검토한 다음 시작하기의 단계에 따라 확인하십시오.
이것이 여러분에게 의미하는 바
- 실행: Node 프로세스(
@ai-sdk/otel가 Amplitude를 가리키도록 설정). 함수 id는 세션 id가 아닙니다. - 필요 항목:
ai@7.0.155,@ai-sdk/otel@1.0.155, Amplitude 프로젝트 API 키, 그리고 모든 턴마다 안정적인 대화 ID 및 제품 분석 사용자 ID가 필요합니다. - 프로토콜: HTTP 기반 OTLP. Amplitude는 protobuf 및 JSON을 허용합니다. Amplitude는 gRPC를 허용하지 않습니다.
- 개인정보 보호: Amplitude는 수신 후 콘텐츠를 삭제하지 않습니다.
recordInputs: false및recordOutputs: false은(는) 메시지 텍스트와 도구 인수를 삭제합니다. 세션, 사용자, 에이전트, 모델, 토큰 수 및 도구 이름은 여전히 도착합니다. 내보내기 전에 콘텐츠 속성을 마스킹하거나 삭제하십시오.
내보내기
에이전트 프로세스에서 이러한 변수를 설정합니다. 헤더 값이 환경 변수에 있는 경우 헤더 값의 공백을 %20으(로) 인코딩합니다. Authorization=을(를) 그대로 두십시오.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.amplitude.com/otlp/v1/traces
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<project API key>"
OTEL_SERVICE_NAME=order-support
EU 데이터 레지던시 https://api.eu.amplitude.com/otlp/v1/traces을(를) 사용합니다.
SDK 7에서 첫 번째 모델을 호출하기 전에 registerTelemetry(new OpenTelemetry({ enrichSpan }))을(를) 호출하십시오. enrichSpan는 gen_ai.conversation.id, user.id, gen_ai.agent.id을(를) 설정합니다. SDK 6에서는 experimental_telemetry을(를) 활성화하고 스팬 프로세서에서 해당 세 가지 속성을 설정하십시오. 도구 루프에서 stopWhen: stepCountIs(...)을(를) 설정하여 최종 모델 호출에 회신 텍스트가 포함되도록 합니다. Amplitude는 SDK 6 ai.generateText.doGenerate을(를) 모델 호출로, ai.toolCall을(를) 도구 호출로 매핑합니다. 상위 ai.generateText 스팬은 스팬으로 유지됩니다.
아이덴티티
| 속성 | 값 |
|---|---|
gen_ai.conversation.id | 대화, 스레드 또는 티켓 ID입니다. 모든 턴에 동일한 값을 사용합니다. |
user.id | 프로덕트 분석에서 이미 사용하고 있는 사용자 ID입니다. Amplitude는 누락된 사용자를 unknown으(로) 저장합니다. |
gen_ai.agent.id | 이 에이전트의 안정적인 이름. Amplitude는 gen_ai.agent.name을(를) 읽지 않습니다. |
이월되는 항목
| AI SDK 스팬 | Amplitude 이벤트 |
|---|---|
모델 호출 (chat) | [Agent] AI Response 및 마지막 어시스턴트 메시지 이후의 각 새 사용자 메시지에 대한 [Agent] User Message |
도구 (execute_tool) | [Agent] Tool Call |
| Step 및 에이전트 스팬 | [Agent] Span |
도구 루프 연속은 gen_ai.input.messages 내부의 이전 사용자 텍스트를 반복합니다. Amplitude는 이전 사용자 메시지를 다시 표시하지 않습니다. 도구 출력은 [Agent] Tool Output입니다.
세션 닫기
[Agent] Session End은(는) 선택 사항이며 권장됩니다. 네이티브 AI SDK 내보내기는 이를 전송하지 않습니다. Amplitude는 기본적으로 적합한 에이전트 이벤트 없이 30분 후에 세션을 닫으며, 세션별 재정의가 설정되지 않은 경우 세션 시작 후 24시간 내에 세션을 닫습니다. 첫 번째 종료가 카운트됩니다. 세션 레코드와 콘텐츠 기반 신호를 포함한 보강 작업(Enrichment)은 해당 종료 후 한 번 실행됩니다. OpenTelemetry 변환기는 스팬에서 idle-timeout 속성을 읽지 않습니다. 세션 닫기 방법을(를) 참조하십시오.
시작하기
Vercel AI SDK 연동 가이드를 따르십시오. 동일한 대화 ID로 두 턴을 전송한 다음 라이브 이벤트에서 확인하십시오:
- 세션 ID는
gen_ai.conversation.id이며, 추적 ID가 아닙니다. - 사용자 ID는 product-analytics 사용자가 아니라
unknown입니다. - 에이전트 ID는
gen_ai.agent.id입니다. - 해당 턴에는 사용자 메시지 텍스트, 도구 호출 및 AI 응답 텍스트가 표시되며, 모델 이름과 두 토큰 카운트가 포함됩니다.
- 두 번째 턴은 첫 번째 사용자 메시지를 복제하지 않습니다.
가이드는 2026년 10월 28일에 ai7.0.155, @ai-sdk/otel1.0.155 및 ai6.0.317 버전을 대상으로 마지막으로 확인되었으며, @ai-sdk/openai2.0.138 버전과 함께 검증되었습니다. Vercel 및 AI SDK는 해당 소유주의 상표입니다. Amplitude는 해당 소유자와 제휴 관계가 아니며 해당 소유자의 보증을 받지 않습니다.
이 내용이 도움이 되었나요?
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.