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
変更を確認し、今すぐ始めるの手順に従って確認します。
必要な対応
- 実行するもの:Strandsプロセス(OpenTelemetryエクスポータをAmplitudeにポイントします)。コレクタはオプションです。gRPCスパンをすでに収集している場合や、そこで属性をスクラブする場合は、それを使用してください。
- 必要なもの:
strands-agents[otel]==1.60.0、AmplitudeプロジェクトのAPIキー、およびすべてのターンで変わらない会話IDとプロダクト分析ユーザーID。 - プロトコル:OTLP over HTTP。AmplitudeはprotobufとJSONを受け入れます。AmplitudeはgRPCを受け入れません。OTLP/HTTPをエクスポートするコレクタを介してgRPCをブリッジします。
- プライバシー: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、model、およびtokenのカウントは引き続き到着できますが、メッセージテキストは到着しません。
Agent()を構築する前にStrandsTelemetry().setup_otlp_exporter()を呼び出します。トレーサープロバイダーがすでにインストールされている場合は、それを渡します:
from opentelemetry import trace
from strands.telemetry import StrandsTelemetry
StrandsTelemetry(tracer_provider=trace.get_tracer_provider()).setup_otlp_exporter()
アイデンティティ
エージェントの構築時に、trace_attributesディクショナリを1つ渡します。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は、その以前のユーザーメッセージを再度送信しません。ツールの出力は[プレースホルダー]です[Agent] Tool Output。システム指示(存在する場合)は、AI Responseに[Agent] System Prompt表示されます。 feature_flag.evaluationスパンイベントまたは[Agent] Experiment*スパン属性がfeature_flag.*プロパティになります。機能フラグの属性を参照してください。
セッションの終了
[Agent] Session Endはオプションであり、推奨されます。ネイティブのStrandsエクスポートでは、この値は送信されません。 Amplitudeは、デフォルトで有効なイベントが30分間発生しない場合にセッションを終了します。また、セッションごとのオーバーライドが設定されていない場合は、セッション開始から24時間後にセッションが終了します。最初に閉じたものがカウントされます。セッションレコードとコンテンツベースのシグナルを含むエンリッチメントは、その終了後に一度実行されます。 このレコードは、通常、取り込みバッチがcloseを処理してから15~20分後に到着します。バックログの期間中は、より長くかかることがあります。Amplitudeは、closeの後に到着するイベントを保存します。これらのイベントはそのレコードを再計算しません。
作業単位が完了したとわかったら、[Agent] Session IDと同じsession.idを持つ1つの[Agent] Session EndをHTTP API経由で送信します。純粋なStrandsエクスポートでは、サーバーのデフォルト値を使用します。 OpenTelemetryトランスレータは、スパンからidle-timeout属性を読み取ることはありません。 アイドル時間枠を変更するには、HTTP [Agent] Contextキーidle_timeout_minutesを送信するか、そのSession Endイベントに[Agent] Session Idle Timeout Minutesを設定します。セッションの終了方法を参照してください。
アプリがすでにSDKを実行している場合
エージェントプロセスですでにAmplitude AI SDKを使用している場合、AmplitudeAgentExporterまたはenableOtel()でそのプロセス内のスパンをマップできます。上記のネイティブ OTLP は、SDK がロードされていない場合のパスです。 SDK redactPiiはプロセス内パスにのみ適用されます。
今すぐ始める
Strands連携ガイドに従ってください。同じsession.idの2つのターンを送信し、ライブイベントで確認します。
- セッションIDは
session.idであり、トレースIDではありません。 - ユーザーIDはプロダクト分析ユーザーであり、
unknownではありません。 - エージェントIDは
gen_ai.agent.idです。 - ターンには、ユーザーメッセージのテキスト、ツール呼び出し、AIレスポンスのテキストが表示されます。また、モデル名と両方のトークン数も含まれます。
ada@example.comと555-123-4567のカナリアは、それぞれ[email]および[phone]として保存されます。生の値は存在しません。- 2番目のターンでは、最初のユーザーメッセージは複製されません。
括弧で囲まれた米国(US)の電話番号は、始めの括弧がそのまま残ります。例えば、Call (555) 123-4567はCall ([phone]に変換されます。
ガイドの最終確認日は2026年10月14日で、対象バージョンはstrands-agents1.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.