Agent 365 gözlemlenebilirlik kavramları

Bu makale, Agent 365 gözlemlenebilirliğinin arkasındaki veri modelini açıklıyor - telemetri aracılarının ne yaydığı, kimler yayabileceği, nereye indiği ve uygulanan sınırlar. Bu kavramlar her entegrasyon yolu için geçerlidir: Microsoft OpenTelemetry Distro, Agent 365 SDK ve doğrudan OTel.

Not

Protokol düzeyindeki detaylar - Kimlik Doğrulama içindeki URL rotaları, Limitler ve bırakma koşulları içindeki HTTP hata kodları ve istek başına boyut ile hız limitleri - yalnızca doğrudan OTel yoluna uygulanır. SDK ve Distro bunları sizin için soyutlar. Bu makalenin geri kalanı (terimler, veri akışı, kimlik modelleri, kapsamlar, bırakma koşulları, verinin görüntülendiği yerler) her yol için geçerlidir.

Entegrasyon yolunuzu seçin

Üç yol, aynı span veri modelini Agent 365'e iletir. Birini seçin:

  • Microsoft OpenTelemetry Dağıtım - yeni entegrasyonlar için önerilir. Agent 365, Microsoft Atölye, Azure İzleyici ve daha fazlası genelinde birleşik gözlemlenebilirlik SDK'sı.
  • Agent 365 SDK (Gözlemlenebilirlik SDK'sı) - önceki SDK. Bozulmadan çalışmaya devam ediyor, ancak yeni entegrasyonlar için artık önerilen yol değil; mevcut SDK kullanıcıları için geçiş rehberi yakında yayımlanacak.
  • Doğrudan OTel - ham OTLP/HTTP yöntemi. Bunu yalnızca mevcut bir OpenTelemetry veri hattınız varsa, aracı framework'ünüz Agent 365 SDK'yı kullanamıyorsa veya aracınız SDK'nın henüz desteklemediği bir dildeyse (örneğin Java) kullanın.

Hangi yolu seçerseniz seçin, aşağıda açıklanan veri modeli, kimlik modelleri, kapsamlar, sınırlar ve platformlar geçerlidir.

Sözlük

  • Uygulama kimliği (appId): Bir Microsoft Entra uygulaması veya Microsoft Entra Aracı Kimliği aracı kimliği kaydedildiğinde verilen uygulama tanımlayıcısı.
    • OAuth client_id ile eşdeğerdir, Microsoft Entra nesne kimliğine eşit değildir.
    • Bu belgelerde, "aracı kimliği" ve "blueprint id" her ikisi de bir appId anlamına gelir.
  • Konuşma: Mantıksal bir aracı etkileşim dizisi; örneğin bir Teams sohbet dizisi.
    • gen_ai.conversation.id ile tanımlanır.
    • Bir koşu için birincil birleştirme anahtarı.
  • Kanal: Aracının çalıştığı yüzey: msteams, outlook, web ve benzeri.
  • Çalışma: Bir kullanıcı mesajı ve bir aracı yanıtı. OTel span'larının bir ağacı olarak modellenmiştir. traceId

Nasıl çalışır

Agent 365'in genel görünümü ve telemetri verilerinin hangi yüzeylere aktarıldığı için Microsoft Agent 365 Genel Bakış bölümüne bakınız.

Telemetriyi OpenTelemetry iz verisi biçiminde gönderirsiniz:

  • Bir span ağacı, bir çalıştırmayı tanımlar (bir kullanıcı mesajı girer, bir aracı yanıtı çıkar).
  • Her span bir adımı tanımlar: en üst düzey aracı çağrısı, bir LLM çağrısı, bir araç çağrısı veya son yanıt.

Veri akışı

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

Kimlik modelleri

Aracı kimlik modellerinin (standart Microsoft Entra uygulama kaydı ve Microsoft Entra Aracı Kimliği aracı kimlik şablonu, yapay zeka ekip üyeleri dahil) tam açıklaması için Agent 365 geliştirmeye başlama bölümüne bakın. Seçtiğiniz kimlik modeli, hangi kimlik doğrulama akışını ve uç noktayı kullanacağınızı belirler.

Aracınızın Microsoft Entra kaydı yoksa bu rotaları doğrudan kullanamaz. Aracıyı alternatif kimlik özellikleri ile tanımlayın (bkz. Özellik referansı) ve uygun giriş yolunu öğrenmek için Agent 365 ekibiyle iletişime geçin.

Kimlik Doğrulaması

Doğrulama, hizmetinizin kendisi mi yoksa kullanıcı adına mı gerçekleştiğine göre dallanır. Dallanma, OAuth akışını, izni taşıyan token iddiasını ve URL rotasını belirler.

  • Hizmet kendi kendini doğrular: Oturum açmış kullanıcı yoktur - otonom, zamanlanmış veya olay tetikli.

    • OAuth akışı: Hizmetler arası (S2S) istemci kimlik bilgileri.
    • Belirteç iddiası: roles.
    • URL rotası: /observabilityService/....

  • Hizmet bir kullanıcı adına kimlik doğrulaması yapar: Yapay zeka ekip arkadaşları için veya aracının kendi kullanıcı hesabı için.

    • OAuth akışı: On-behalf-of (OBO).
    • Belirteç iddiası: scp.
    • URL rotası: /observability/....

Aynı aracı uygulaması, her iki akışta da yer alabilir; örneğin, her gece otonom özetleme işlemi gerçekleştiren bir yapay zeka takım arkadaşı gibi. Daha fazla bilgi için otonom uygulama OAuth akışı ve Kullanıcı Adına akışı bölümlerine bakınız.

Kimlik modeli ve akışın her kombinasyonu için tam token yapılandırmalarını Entegrasyon rehberindeki Kimlik Doğrulama yapılandırmaları bölümünde bulabilirsiniz.

Aracı kimliği URL'ye bağlıdır

URL'deki {agentId} parametresi, çağıran uygulamanın appId değerine eşit olmalıdır (tokenınızda appid veya azp claim olarak bulunur). Uyumsuzluk durumunda 403 Forbidden yanıtı verilir. Şablon tabanlı kimlikler için {agentId}, şablon uygulama kimliği değil, aracı kimliği uygulama kimliğidir.

Ayrıca, ilettiğiniz her span için gen_ai.agent.id değerini aynı appId olarak ayarlamanız gerekir; sunucu, yük içindeki aracı kimliğini doğrulanmış aracı ile karşılaştırır ve eşleşmeyenleri reddeder. Bu adım, birden fazla aracıdan gelen span'lerin yanlışlıkla tek bir istekte karışmasını tespit eder.

Bir kapsam (delege edilmiş) veya uygulama rolü (uygulama), Microsoft Entra'nın erişim belirtecine oluşturduğu adlandırılmış izindir. Agent 365 telemetrisinde, izin Agent365.Observability.OtelWrite Agent 365 Observability kaynağı üzerinde (audience 9b975845-388f-4429-889e-eab1ef63949c) tanımlanır.

Aynı izin adı her iki türde de kaydedilmiştir:

  • Otonom (S2S / istemci kimlik bilgileri) akışı için uygulama rolü. roles claim'inde yer alır. <resource>/.default tarafından seçilir.
  • Delege edilmiş kapsam OBO akışı için. scp claim'inde yer alır. <resource>/Agent365.Observability.OtelWrite (veya <resource>/.default) tarafından seçilir.

Agent 365 ayrıca Agent365.Observability.OtelRead okuma izni sunar; bu izin, Agent 365 telemetrisini sorgulayan operatörler tarafından kullanılır. Çoğu partnerin buna ihtiyacı yok - bu belgeler yalnızca veri alımını kapsar.

Uygulamanıza API izni ekleme

  • Bir standart Microsoft Entra uygulama kaydı için: Azure portalında, aracı uygulamasının kaydında API izinleri altında Agent365.Observability.OtelWrite (S2S için uygulama rolü, delegasyon için kapsam) ekleyin.
  • Blueprint için: Microsoft Entra Aracı Kimliği aracı kimliği blueprint'inden oluşturulan aracılar, blueprint üzerinde tanımlanan OAuth izinlerini devralır; böylece kiracı yöneticisi izinleri bir kez önceden tanımlar. Bu blueprint'ten oluşturulan her aracı örneği ilgili izinleri otomatik olarak elde eder. Bkz. Aracı kimliği blueprintleri için miras alınabilir izinleri yapılandırma.

Belirteçler rolü/kapsamı taşımadan önce, müşteri kiracısında bir kiracı yöneticisi tarafından onay verilmelidir. Bkz. Aracılara Microsoft 365 kaynaklarına erişim izni verme.

Onay olmadan, belirteç edinimi AADSTS65001 ("kullanıcı veya yönetici onay vermedi") hatasıyla başarısız olur veya belirteç roles / scp beyanı olmadan verilir ve veri toplama uç noktası isteği 403 ile reddeder.

Onay her kiracı için bir kez verilir ve bundan sonra şablondan oluşturulan her örneğe uygulanır. Yeniden onay yalnızca blueprint'e yeni bir izin eklendiğinde gereklidir.

Sınırlar ve veri bırakma koşulları

Bu limitleri önceden bilmek entegrasyon sırasında sürprizleri önler – çoğu sessizdir (API isteği kabul eder, ancak veri alt akışta asla görünmez).

Bağlantı düzeyi sınırları:

  • api-version=1 her istekte gereklidir.
  • Maksimum istek gövde boyutu 1 MB. Daha büyük istekler 413 Payload Too Large alır.
  • İki endpointin ayrı istek sınırları vardır. 429 üzerinde, Retry-After'ye (1 saniye olarak ayarlanmış ) riayet edin ve rastgele gecikmeyle geriye çekilin.

Hata yanıtları:

  • 403 Forbidden--belirteçte gerekli uygulama rolü/kapsamı eksik veya URL'deki {agentId} belirtecinizin appid / azp ile eşleşmiyor.
  • 413 Payload Too Large--gövde 1 MB'yi aşıyor.
  • 429 Too Many Requests--oran sınırı aşıldı; Retry-After: 1 değerine uyun ve rastgele gecikmeyle geri çekilin.

Düşürme koşulları (HTTP tarafından kabul edilen istek ancak veri aşağı akışta görünmüyor):

# Koşul Davranış
1 Span gen_ai.operation.name eksik veya {invoke_agent, execute_tool, chat, output_messages} içinde değil Span bazında veri atımı. Şu yüzeylerde görüntülendi partialSuccess.rejectedSpans + errorMessage.
2 Müşteri kiracındaki hiçbir kullanıcıya Microsoft 365 E7 veya Microsoft Agent 365 lisansı atanmış değildir. Kiracıdaki en az bir kullanıcıya lisans atanmış olmalıdır (SKU'nun kiracıda bulunması yeterli değildir – atama, Defender arka plan işlem akışını başlatır). Lisanslı kullanıcının, aracıyı çağıran kişi olması gerekmez. Tüm istek sessizce görmezden gelindi. 200 { "partialSuccess": null } değerini döndürür.

200 OK ise tüketme kanıtı değildir. Verinin ulaştığını doğrulamak için doğrulama akışını kullanın.

Verilerinizin göründüğü yerler

Kabul edildikten sonra, span’leriniz müşteri odaklı üç deneyimde görüntülenir. Üçü de koşunun kökünde geçerli bir invoke_agent span'a bağlıdır. Yalnızca chat / execute_tool / output_messages aralık içeren bir çalışma, Defender gelişmiş avcılığında sorgulanabilir (CloudAppEvents tablosu), ancak aşağıdaki diğer tüm yüzeylerde görünmezdir.

Microsoft Defender. Aracı etkinlikleri (invoke_agent, execute_tool, chat) aracı etkinlik görünümlerinde görüntülenir. Kiracı yöneticileri ve güvenlik analistleri, bireysel koşulara, araçlara ve çıkarım çağrılarına ayrıntılı olarak erişebilir. Aracı-etkinlik görünümleri invoke_agent span'e göre çalışır; bu olmadan, alt span'ler gelişmiş arama yoluyla sorgulanabilir olsa bile, çalıştırma orada görünmez. İleri-avlama görünümü - CloudAppEvents - her işlemi kabul eder: ActionType işlemi gösterir (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) ve her span'a ait alanlar RawEventData içinde yer alır. Müşteri tarafından görülebilen alan adları, ilettiğiniz span nitelikleriyle doğrudan eşlenir: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id ve devamı. Tam eşleştirme için Öznitelik referansına bakınız.

Microsoft 365 yönetim merkezi. Aracı etkinliği, kiracı yöneticilerinin kiracılarındaki aracıları yönetmek için kullandığı aracı-envanteri ve güvenlik görünümlerinde de görüntülenir. Yönetim merkezi yalnızca invoke_agent satırları alır: invoke_agent telemetrisi olmayan aracılar envanterde görünmez ve yalnızca chat / execute_tool / output_messages yayan çalıştırmalar burada görünmez. Yönetim merkezinin okuduğu özellikler (aracı kimliği, aracı adı, blueprint kimliği, arayan kimliği, konuşma kimliği, kanal, hata durumu) tümü invoke_agent span'ından alınır.

Microsoft Purview. Aracı etkinlikleri, Microsoft Purview'da uyum yöneticileri için görünür olur; burada aracı çalıştırmaları üzerinde veri işleme ve politika kuralları (veri kaybının önlenmesi, saklama, iletişim uyumu ve benzerleri) yapılandırılabilir. Purview politikalarının anahtarı olan özellikler (aracı kimliği / blueprint kimliği, arayan kimliği, konuşma / kanal, talep ve yanıt mesajları) hepsi aralıktan invoke_agent ve onun soy noktalarından gelir.

Sonraki adımlar

  • Öznitelik referansı - Her öznitelik için tanımlama, gereksinimler ve değer seçimi rehberi.
  • Sorun giderme - Alımı doğrulama, yaygın sorunlar ve hata yanıtları.
  • Last updated on