Microsoft Agent Framework 트레이스를 에이전트 분석으로 전송

Microsoft Agent Framework는 OpenTelemetry GenAI 스팬을 생성합니다. 해당 Exporter를 Amplitude로 설정하십시오. 에이전트 프로세스에서 Amplitude AI SDK는 필요하지 않습니다. AutoGen 사용자는 이 페이지를 팔로우합니다.

이 페이지에서는 Python의 agent-framework-core 1.23.0 및 agent-framework-openai 1.17.0, 그리고 Microsoft.Agents.AI의 Microsoft.Agents.AI.OpenAI 1.26.0에 대해 설명합니다. .NET. Amplitude는 내보낸 스팬을 저장합니다. 개인 데이터가 인프라를 떠나기 전에 비식별화하십시오. 에이전트 분석 개인정보 보호 모드를 참조하십시오.

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

이 프롬프트를 Cursor, Claude Code, Windsurf, GitHub Copilot 또는 Codex와 같은 AI 코딩 에이전트에 붙여넣으십시오.

text
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를 기록합니다. 프레임워크는 span 시작 후 대화 id를 덮어씁니다.
  • 필요한 항목: agent-framework-core==1.23.0, agent-framework-openai==1.17.0, Amplitude 프로젝트 API 키, 안정적인 에이전트 ID, 대화 ID 및 product-analytics 사용자 ID입니다.
  • 프로토콜: HTTP 기반 OTLP. Amplitude는 protobuf 및 JSON을 허용합니다. Amplitude는 gRPC를 허용하지 않습니다.
  • 개인정보 보호: Amplitude는 콘텐츠를 수신한 후 삭제하지 않습니다. 메타데이터만 사용하려면 ENABLE_SENSITIVE_DATA을(를) 설정하지 않은 상태로 두십시오. 세션, 사용자, 에이전트, 도구 이름, 모델 및 토큰 카운트가 여전히 도착합니다. 메시지 텍스트 및 도구 인수는 그렇지 않습니다. 켜져 있는 경우 내보내기 전에 콘텐츠 속성을 마스킹하거나 삭제하십시오.

내보내기

프로세스가 프레임워크를 가져오기 전에 이러한 변수를 설정합니다. Python에서 헤더 값의 스페이스를 %20으(로) 인코딩합니다. Authorization= 기록된 대로 둡니다.

bash
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)을(를) 한 번 호출하십시오. id을(를) Agent에 전달하여 gen_ai.agent.id이(가) 생성된 UUID가 아닌 안정적인 이름이 되도록 하십시오. 익스포터 래퍼에 user.id, session.id, gen_ai.conversation.id 및 gen_ai.agent.id을(를) 표시합니다. span 프로세서의 on_start는 프레임워크가 공급자 응답 id를 gen_ai.conversation.id에 기록하기 전에 실행되며, Amplitude는 해당 대화 id를 먼저 읽습니다.

아이덴티티

이월되는 내용

도구 출력은 [Agent] Tool Output입니다. 이 캡처의 continuation 범위에는 도구 결과가 포함되므로 첫 번째 사용자 메시지가 다시 표시되지 않습니다.

.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시간이 지나면 세션을 닫습니다. 첫 번째 종료가 집계됩니다. 세션 레코드와 콘텐츠 기반 신호를 포함한 Enrichment는 해당 종료 시점 이후 한 번 실행됩니다. OpenTelemetry 변환기는 스팬에서 idle-timeout 속성을 읽지 않습니다. 세션 닫기 방법을 참조하십시오.

시작하기

Microsoft Agent Framework 연동 가이드를 따르십시오. 동일한 대화 ID로 두 턴을 전송한 다음 라이브 이벤트에서 확인하십시오:

  1. 세션 ID는 대화 ID이며, 공급자 응답 ID나 추적 ID가 아닙니다.
  2. 사용자 ID는 product-analytics 사용자가 아니라 unknown입니다.
  3. Agent ID는 사용자가 설정한 에이전트 id이며 생성된 UUID가 아닙니다.
  4. 민감한 데이터가 활성화된 경우, 턴에는 사용자 메시지 텍스트, 도구 호출 및 AI 응답 텍스트가 표시되며, 모델 이름과 두 토큰 카운트가 표시됩니다. EnableSensitiveData이 설정이 해제되면 메시지 텍스트와 도구 인수가 도착하지 않습니다.
  5. 두 번째 턴은 첫 번째 사용자 메시지를 복제하지 않습니다.

이 가이드는 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.

이 페이지에서