AWS Strands 추적을 에이전트 분석으로 전송
Python Strands Agents SDK는 OpenTelemetry GenAI 스팬을 방출합니다. 해당 익스포터를 Amplitude로 지정하십시오. 에이전트 프로세스에서 Amplitude AI SDK는 필요하지 않습니다.
이 페이지에서는 Strands 에이전트 1.60.0에 대해 설명합니다. Amplitude는 내보낸 스팬을 저장합니다. 개인 데이터가 인프라를 벗어나기 전에 비식별화하십시오. 에이전트 분석 개인정보 보호 모드를 참조하십시오.
AI 코딩 에이전트로 설정(권장)
이 프롬프트를 Cursor, Claude Code, Windsurf, GitHub Copilot 또는 Codex와 같은 AI 코딩 에이전트에 붙여넣으십시오.
Connect this Python Strands agent to Amplitude Agent Analytics with native OpenTelemetry.
Fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/strands.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
변경 사항을 검토한 다음 Get started의 단계에 따라 확인하십시오.
이것이 여러분에게 의미하는 바
- 실행 방법: Amplitude를 가리키는 OpenTelemetry 내보내기가 포함된 Strands 프로세스를 실행합니다. Collector는 선택 사항입니다. 이미 gRPC 스팬을 수집하거나 해당 스팬에서 속성을 스크러빙할 때 사용하십시오.
- 필요한 사항은
strands-agents[otel]==1.60.0, Amplitude 프로젝트 API 키, 그리고 매 턴에 안정적인 대화 ID 및 product-analytics 사용자 ID입니다. - 프로토콜: HTTP 기반 OTLP. Amplitude는 protobuf 및 JSON을 허용합니다. Amplitude는 gRPC를 지원하지 않습니다. OTLP/HTTP를 내보내는 Collector를 통해 gRPC를 Bridge합니다.
- 개인정보 보호: Amplitude는 콘텐츠를 수신한 후 스크러빙하지 않습니다. 내보내기 전에 콘텐츠 속성을 마스킹하거나 삭제하십시오.
내보내기
에이전트 프로세스에서 이러한 변수를 설정합니다. Python에서 헤더 값의 스페이스를 %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
OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental,gen_ai_tool_definitions,gen_ai_span_attributes_only
EU 데이터 상주 기능은 https://api.eu.amplitude.com/otlp/v1/traces를 사용합니다.
gen_ai_span_attributes_only은(는) 스팬 속성에 프롬프트, 완성 및 시스템 지침을 포함합니다. Amplitude는 스팬 이벤트를 읽지 않습니다. 해당 플래그가 없으면 ID, 모델 및 토큰 카운트가 여전히 도착할 수 있으며 메시지 텍스트는 도착하지 않습니다.
StrandsTelemetry().setup_otlp_exporter()을(를) 호출하기 전에 Agent()을(를) 구성하십시오. 트레이서 프로바이더가 이미 설치된 경우 이를 전달하십시오.
from opentelemetry import trace
from strands.telemetry import StrandsTelemetry
StrandsTelemetry(tracer_provider=trace.get_tracer_provider()).setup_otlp_exporter()
아이덴티티
에이전트를 구성할 때 trace_attributes 사전 하나를 전달하세요. Strands는 이를 모델 스팬과 각 도구 스팬에 복사합니다.
| 속성 | 값 |
|---|---|
session.id | 대화, 스레드 또는 티켓 ID입니다. 모든 턴에 동일한 값을 사용합니다. |
user.id | 프로덕트 분석에서 이미 사용하고 있는 사용자 ID입니다. Amplitude는 누락된 사용자를 unknown(으)로 저장합니다. |
gen_ai.agent.id | 이 에이전트에 대한 안정적인 이름입니다. Amplitude는 gen_ai.agent.name를 읽지 않습니다. |
gen_ai.provider.name | 모델을 제공한 공급자(예: aws.bedrock). |
Strands는 trace_attributes이(가) 이후에 설정하지 않는 한 gen_ai.provider.name=strands-agents을(를) 작성합니다. 실제 공급자를 설정합니다. Amplitude는 스팬에 gen_ai.usage.cost이(가) 포함된 경우에만 비용을 기록합니다.
이월되는 항목
| Strands 스팬 | Amplitude 이벤트 |
|---|---|
모델 호출 (chat) | [Agent] AI Response, 그리고 마지막 어시스턴트 메시지 이후 새로운 사용자 메시지마다 [Agent] User Message이(가) 추가됩니다 |
도구 (execute_tool) | [Agent] Tool Call |
| 에이전트 및 주기 범위 | [Agent] Span |
나중 턴에서는 gen_ai.input.messages 내부의 이전 사용자 텍스트가 반복됩니다. Amplitude는 이전 사용자 메시지를 다시 표시하지 않습니다. Tool 출력은 [Agent] Tool Output입니다. 시스템 지침(있는 경우)은 AI 응답에 [Agent] System Prompt있습니다. feature_flag.evaluation span 이벤트 또는 feature_flag.* span 속성이 [Agent] Experiment* 속성이 됩니다. 기능 플래그 속성을 참조하십시오.
세션 닫기
[Agent] Session End은(는) 선택 사항이며 권장됩니다. 네이티브 Strands 내보내기는 이를 전송하지 않습니다. Amplitude는 기본적으로 적합한 에이전트 이벤트 없이 30분 후에 세션을 닫으며, 세션별 재정의가 설정되지 않은 경우 세션 시작 후 24시간 내에 세션을 닫습니다. 첫 번째 종료가 계산됩니다. 세션 레코드와 콘텐츠 기반 신호를 포함한 Enrichment는 해당 종료 후 한 번 실행됩니다. 일반적으로 레코드는 수집 배치가 종료를 처리한 후 15~20분 후에 도착하며, 백로그 발생 시 더 오래 걸릴 수 있습니다. Amplitude는 닫기 후 도착하는 이벤트를 저장하며, 해당 이벤트는 해당 레코드를 재계산하지 않습니다.
작업 단위가 완료된 것을 확인하면, [Agent] Session ID과(와) 동일한 session.id를 사용하여 HTTP API를 통해 [Agent] Session End 하나를 전송하십시오. 순수 Strands 내보내기는 서버 기본값을 사용합니다. OpenTelemetry 변환기는 스팬에서 idle-timeout 속성을 읽지 않습니다. 유휴 윈도우를 변경하려면 HTTP [Agent] Context 키 idle_timeout_minutes를 전송하거나, 해당 세션 종료 이벤트에 [Agent] Session Idle Timeout Minutes을(를) 설정하십시오. 세션 닫기 방법을 참조하십시오.
앱이 이미 SDK를 실행하는 경우
에이전트 프로세스가 이미 Amplitude AI SDK를 사용하는 경우 AmplitudeAgentExporter 또는 enableOtel()은(는) 해당 프로세스에서 스팬을 매핑할 수 있습니다. 위의 Native OTLP는 SDK가 로드되지 않을 때 경로입니다. SDKredactPii는 in-process 경로에만 적용됩니다.
시작하기
Strands 연동 가이드를 따르십시오. 동일한 session.id값으로 두 턴을 전송한 다음 라이브 이벤트에서 확인하십시오:
- 세션 ID는
session.id이며, 추적 ID가 아닙니다. - 사용자 ID는 product-analytics 사용자가 아니라
unknown입니다. - 에이전트 ID는
gen_ai.agent.id입니다. - 턴에는 사용자 메시지 텍스트, 도구 호출 및 AI 응답 텍스트가 표시되며, 모델 이름과 두 토큰 카운트가 포함됩니다.
ada@example.com및555-123-4567의 카나리아는[email]및[phone](으)로 저장됩니다. 원시 값이 없습니다.- 두 번째 턴은 첫 번째 사용자 메시지를 복제하지 않습니다.
괄호로 묶인 미국 숫자는 여는 괄호를 유지하며, Call (555) 123-4567은(는) Call ([phone]로 변경됩니다.
가이드는 2026년 10월 14일에 strands-agents 1.60.0 버전을 기준으로 마지막으로 확인되었습니다. Strands는 소유자의 상표입니다. 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.