Microsoft Agent Frameworkのトレースをエージェント分析に送信する
Microsoft Agent FrameworkはOpenTelemetry GenAIスパンを発行します。 そのエクスポータをAmplitudeに向けます。エージェントプロセスではAmplitude AI SDKは必要ありません。 AutoGenユーザーはこのページに従ってください。
このページでは、Pythonではagent-framework-core 1.23.0とagent-framework-openai 1.17.0、.NETではMicrosoft.Agents.AI 1.26.0とMicrosoft.Agents.AI.OpenAI 1.26.0について説明します。Amplitudeは、エクスポートしたスパンを保存します。 個人データがインフラストラクチャを離れる前に、スクラブ(匿名化)してください。エージェント分析のプライバシーモードを参照してください。
AIコーディングエージェントを使用した設定(推奨)
このプロンプトを、Cursor、Claude Code、Windsurf、GitHub Copilot、Codexなどの AI コーディング エージェントに貼り付けます。
Connect this Microsoft Agent Framework agent to Amplitude Agent Analytics with native OpenTelemetry.
Fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/microsoft-agent-framework.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
変更を確認し、今すぐ始めるの手順に従って確認します。
必要な対応
- 実行するもの:Agent Frameworkプロセス(OpenTelemetryエクスポータをAmplitudeにポイントします)。エクスポータにIDを埋め込みます。フレームワークは、スパン開始後にカンバセーションIDを上書きします。
- 必要なもの:
agent-framework-core==1.23.0、agent-framework-openai==1.17.0、AmplitudeプロジェクトのAPIキー、および安定したエージェントID、会話ID、およびプロダクト分析ユーザーID。 - プロトコル:OTLP over HTTP。 AmplitudeはprotobufとJSONを受け入れます。 AmplitudeはgRPCを受け入れません。
- プライバシー:Amplitudeは、受信後にコンテンツをスクラブ(匿名化)しません。メタデータのみの場合は、
ENABLE_SENSITIVE_DATAを未設定のままにしてください。セッション、ユーザー、エージェント、ツール名、モデル、トークンのカウント数は引き続き到着します。メッセージテキストとツール引数は到着しません。オンになっている場合は、エクスポートする前にコンテンツ属性をマスクまたはドロップします。
エクスポート
プロセスがフレームワークをインポートする前に、これらの変数を設定します。 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
ENABLE_SENSITIVE_DATA=true
ENABLE_INSTRUMENTATION=true
EU地域のデータレジデンシーの場合はhttps://api.eu.amplitude.com/otlp/v1/tracesを使用します。
エージェントでのみ、enable_instrumentation(enable_sensitive_data=True)を一度呼び出します。gen_ai.agent.idが生成されたUUIDではなく、安定した名前になるように、idをAgentに渡します。エクスポータラッパーでuser.id、session.id、gen_ai.conversation.id、およびgen_ai.agent.idをスタンプします。スパンプロセッサーのon_startは、フレームワークがプロバイダーレスポンスIDをgen_ai.conversation.idに書き込む前に実行され、Amplitudeが先にその会話IDを読み取ります。
アイデンティティ
| 属性 | 値 |
|---|---|
gen_ai.conversation.id | 会話、スレッド、またはチケットID。 すべてのターンで同じ値を使用します。 |
user.id | プロダクト分析で既に使用されているユーザーIDAmplitudeは、欠落しているユーザーをunknownとして保存します。 |
gen_ai.agent.id | このエージェントの安定した名前。 Agent(id=...)を使用して設定します。Amplitudeはgen_ai.agent.nameを読み取りません。 |
引き継がれるもの
| フレームワークのスパン | Amplitudeイベント |
|---|---|
モデル呼び出し(chat) | [Agent] AI Response、さらに最後のアシスタントメッセージの後に続く新しいユーザーメッセージごとに[Agent] User Message |
ツール(execute_tool) | [Agent] Tool Call |
エージェントスパン(invoke_agent) | [Agent] Span |
ツールの出力は[Agent] Tool Outputです。このキャプチャの連続スパンにはツールの結果が伝送されるため、最初のユーザーメッセージは再び生成されません。
.NET
Microsoft.Agents.AI 1.26.0は、アクティビティソースExperimental.Microsoft.Agents.AI上でchatとexecute_toolを送信します。EnableSensitiveDataを設定して、メッセージテキストとツール引数がスパンに含まれるようにします。デフォルトのままにしておくと、セッション、ユーザー、エージェント、モデル、トークンカウント、ツール名は引き続き到着しますが、メッセージテキストとツール引数は到着しません。 すべてのスパンで、user.id、gen_ai.agent.id、gen_ai.conversation.idを設定します。手順については、Microsoft Agent Framework連携ガイドに記載されています。
セッションを閉じる
[Agent] Session Endはオプションであり、推奨されます。ネイティブのAgent Frameworkエクスポートでは、この情報を送信しません。 Amplitudeは、デフォルトでは条件を満たすイベントがない状態で30分経過するとセッションを終了し、セッションごとのオーバーライドが設定されていない場合はセッション開始から24時間後にセッションを終了します。最初に閉じたものがカウントされます。セッションレコードとコンテンツベースのシグナルを含むエンリッチメントは、その終了後に一度実行されます。OpenTelemetryトランスレータは、スパンからidle-timeout属性を読み取りません。セッションの終了方法を参照してください。
今すぐ始める
Microsoft Agent Framework連携ガイドに従ってください。 同じ会話IDを使用して2つのターンを送信し、ライブイベントで確認します。
- セッションIDは会話IDであり、プロバイダーの応答IDでもトレースIDでもありません。
- ユーザーIDはプロダクト分析ユーザーであり、
unknownではありません。 - エージェントIDは、設定したエージェントIDであり、生成されたUUIDではありません。
- 機密データが有効な場合、turn にはユーザーメッセージテキスト、ツール呼び出し、AI レスポンステキストが表示され、モデル名と両方のトークン数が含まれます。
EnableSensitiveDataがオフの場合、メッセージテキストとツール引数は届きません。 - 2番目のターンでは、最初のユーザーメッセージは複製されません。
ガイドは 2026 年 10 月 28 日に最後に検証されました(対象: agent-framework-core1.23.0、agent-framework-openai1.17.0、Microsoft.Agents.AI1.26.0)。Microsoft Agent Frameworkは、その所有者の商標です。 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.