حزمة SDK للرصد للوكيل 365 المتوقف عن استخدامه

Important

توثق هذه المقالة Agent 365 Observability SDK المتوقفة. التكاملات الحالية لا تزال تعمل، لكن لا تستخدم مجموعة تطوير البرامج هذه للتكاملات الجديدة. للتطوير الجديد، استخدم توزيعة Microsoft OpenTelemetry. قبل تحديث تكامل موجود، راجع دليل الترحيل للغتك:

دليل ترحيل Python
دليل ترحيل JavaScript/TypeScript
دليل الترحيل .NET

للاطلاع على نموذج البيانات الأساسي، والهوية والمصادقة، والنطاقات والموافقة، والحدود التي تنطبق على كل مسار تكامل، انظر مفاهيم قابلية الملاحظة لـ Agent 365.

ملحوظة

تعتبر إمكانية الرصد واحدة من مستويات القدرة المتزايدة في بدء استخدام تطوير Agent 365 وتتناسب مع جميع الأنواع الخاصة بالوكلاء.

للمشاركة في نظام Agent 365 البيئي، أضف قدرات الرصد الخاصة بالعميل 365 إلى وكيلك. يعتمد Agent 365 Observability على OpenTelemetry (OTel) ويوفر إطارا موحدا لالتقاط التليمترية بشكل متسق وأمان عبر جميع منصات الوكلاء. من خلال تنفيذ هذا المكون المطلوب، تمكن مسؤولي تقنية المعلومات من مراقبة نشاط وكيلك في مركز إدارة مايكروسوفت وتسمح لفرق الأمن باستخدام Defender وPurview للامتثال واكتشاف التهديدات.

المزايا الرئيسية

الرؤية من البداية إلى النهاية: التقط بيانات شاملة لكل استدعاء وكيل، بما في ذلك الجلسات، واستدعاءات الأدوات، والاستثناءات، مما يمنحك إمكانية التتبع الكاملة عبر المنصات.
تمكين الأمان والتوافق: تغذية سجلات التدقيق الموحدة في Defender و Purview، مما يتيح سيناريوهات الأمان المتقدمة وإعداد تقارير التوافق لوكيلك.
مرونة عبر المنصات: الاعتماد على معايير OTel ودعم أوقات التشغيل والأنظمة الأساسية المتنوعة مثل Copilot Studio وFoundry وأطر عمل الوكلاء المستقبلية.
كفاءة التشغيل للمسؤولين: توفير إمكانية مراقبة مركزية في مركز إدارة Microsoft 365، وتقليل وقت استكشاف الأخطاء وإصلاحها وتحسين الحوكمة باستخدام عناصر التحكم في الوصول المستندة إلى الأدوار لفرق تكنولوجيا المعلومات التي تدير وكيلك.

الوكلاء المعتمدون

تدعم أنواع الوكلاء التالية إمكانية مراقبة Agent 365:

وكلاء Microsoft Agent 365 المُمكّنون: استخدم حزمة SDK للمرقبة لتهيئة وكيلك.
عوامل المحرك المخصصة: استخدم حزمة SDK الخاصة بالمراقبة لتجهيز وكيلك.
العوامل التعريفية: يتم دعم إمكانية المراقبة خارج الصندوق. لا يلزم تنفيذ SDK.

التثبيت

استخدم هذه الأوامر لتثبيت وحدات المراقبة للغات التي يدعمها Agent 365.

تثبيت حزم قابلية المراقبة ووقت التشغيل الأساسية. تحتاج جميع العوامل التي تستخدم Agent 365 Observability إلى هذه الحزم.

pip install microsoft-agents-a365-observability-core
pip install microsoft-agents-a365-runtime

إذا كان وكيلك يستخدم حزمة Microsoft Agents Hosting، فقم بتثبيت حزمة تكامل الاستضافة. يوفر البرنامج الوسيط الذي يملأ الأمتعة والنطاقات تلقائيا من TurnContext، ويتضمن التخزين المؤقت للرمز المميز لمصدر إمكانية المراقبة.

pip install microsoft-agents-a365-observability-hosting

إذا كان وكيلك يستخدم أحد أطر عمل الذكاء الاصطناعي المدعومة، فقم بتثبيت ملحق الأجهزة التلقائية المقابل لالتقاط بيانات تتبع الاستخدام تلقائيا دون رمز الأجهزة اليدوي. للحصول على تفاصيل الإعداد، راجع التخصيص التلقائي.

# For Semantic Kernel
pip install microsoft-agents-a365-observability-extensions-semantic-kernel

# For OpenAI Agents SDK
pip install microsoft-agents-a365-observability-extensions-openai

# For Microsoft Agent Framework
pip install microsoft-agents-a365-observability-extensions-agent-framework

# For LangChain
pip install microsoft-agents-a365-observability-extensions-langchain

تثبيت حزم قابلية المراقبة ووقت التشغيل الأساسية. تحتاج جميع العوامل التي تستخدم Agent 365 Observability إلى هذه الحزم.

npm install @microsoft/agents-a365-observability
npm install @microsoft/agents-a365-runtime

إذا كان وكيلك يستخدم حزمة @microsoft/agents-hosting ، فقم بتثبيت حزمة تكامل الاستضافة. يوفر البرنامج الوسيط الذي يملأ الأمتعة والنطاقات تلقائيا من TurnContext، ويتضمن التخزين المؤقت للرمز المميز لمصدر إمكانية المراقبة.

npm install @microsoft/agents-a365-observability-hosting

// For OpenAI Agents SDK
npm install @microsoft/agents-a365-observability-extensions-openai

// For LangChain
npm install @microsoft/agents-a365-observability-extensions-langchain

قم بتثبيت حزمة المراقبة الأساسية ووقت التشغيل. تحتاج جميع العوامل التي تستخدم Agent 365 Observability إلى هذه الحزمة.

dotnet add package Microsoft.Agents.A365.Observability.Runtime

إذا كان وكيلك يستخدم Microsoft. Agents.A365.Observability.Hosting حزمة NuGet، قم بتثبيت حزمة تكامل الاستضافة. يوفر البرنامج الوسيط الذي يملأ الأمتعة تلقائيا من TurnContext، ويتضمن التخزين المؤقت للرمز المميز لمصدر إمكانية المراقبة.

dotnet add package Microsoft.Agents.A365.Observability.Hosting

// For Semantic Kernel
dotnet add package Microsoft.Agents.A365.Observability.Extensions.SemanticKernel

// For OpenAI
dotnet add package Microsoft.Agents.A365.Observability.Extensions.OpenAI

// For Agent Framework
dotnet add package Microsoft.Agents.A365.Observability.Extensions.AgentFramework

الإعداد

استخدم الإعدادات التالية لتفعيل وتخصيص قابلية الرصد للوكيل 365 لوكيلك.

قم بتعيين متغير البيئة ENABLE_A365_OBSERVABILITY_EXPORTER إلى true لتحقيق الملاحظة. في Agent 365 SDK 2.0 وما بعده، يستخدم المُصدِّر دائمًا مسار الخدمة إلى الخدمة (S2S) ويصادق باستخدام بيانات اعتماد التطبيق فقط المُكوَّنة token_resolver. إذا فعلت المُصدِّر بدون مُحلِّل، يحتفظ Python بالرجوع إلى مُصدِّر وحدة التحكم كخيار احتياطي ولا يرسل بيانات القياس عن بُعد إلى Agent 365.

from microsoft_agents_a365.observability.core import configure

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Return a validated app-only observability token for this agent and tenant.
    return "<app-only-observability-token>"

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_resolver,
)

يتم استبعاد حل الرموز من تسجيل الدخول إلى وحدة التحكم.

يمكنك تخصيص سلوك المصدر عن طريق تمرير مثيل Agent365ExporterOptions إلى exporter_options. ** عندما يتم توفير exporter_options، يكون له الأسبقية على المعامل token_resolver والمعامل cluster_category.

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    exporter_options=Agent365ExporterOptions(
        cluster_category="prod",
        token_resolver=token_resolver,
    ),
    suppress_invoke_agent_input=True,
)

يصف الجدول التالي المعلمات الاختيارية ل configure().

المعامل	الوصف	Default
`logger_name`	اسم مسجل Python المستخدم لتصحيح الأخطاء وإخراج سجل وحدة التحكم.	`microsoft_agents_a365.observability.core`
`exporter_options`	مثيل `Agent365ExporterOptions` يقوم بتكوين محلل الرمز المميز وفئة نظام المجموعة معا.	`None`
`suppress_invoke_agent_input`	عندما `True`، يمنع رسائل الإدخال على `InvokeAgent` النطاقات.	`False`

يصف الجدول التالي الخصائص الاختيارية ل Agent365ExporterOptions.

الملكية	الوصف	Default
`use_s2s_endpoint`	أصبح متقادمًا ويتم تجاهله. يستخدم Agent 365 SDK 2.0 وما بعده دائمًا مسار S2S، حتى عندما تكون هذه القيمة `False`.	`False` (متجاهل)
`max_queue_size`	الحد الأقصى لحجم قائمة الانتظار لمعالج الدفعات.	`2048`
`scheduled_delay_ms`	التأخير بالمللي ثانية بين دفعات التصدير.	`5000`
`exporter_timeout_ms`	المهلة بالمللي ثانية لعملية التصدير.	`30000`
`max_export_batch_size`	الحد الأقصى لحجم الدفعة لعمليات التصدير.	`512`

قم بتعيين متغير البيئة ENABLE_A365_OBSERVABILITY_EXPORTER إلى true لتحقيق الملاحظة. في Agent 365 SDK 2.0 وما بعده، يستخدم المُصدِّر دائما مسار S2S ويصادق باستخدام مُحدِّد رمز الوصول المكوَّن للتطبيق فقط. إذا فعّلت مُصدِّر Agent 365 بدون محلّل الأسماء، يفشل التكوين.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';

// Define a token resolver that returns a validated app-only observability token.
const tokenResolver = (agentId, tenantId) => {
    // Your app-only token resolution logic here.
    return "your-token";
};

// Advanced configuration with builder pattern
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

كبديل لمتغيرات البيئة، يمكنك تكوين إمكانية المراقبة برمجيا باستخدام موفر تكوين من خلال withConfigurationProvider الأسلوب . إذا كنت تستخدم أيضا أساليب المنشئ الفردية (مثل withExporterOptions أو withClusterCategory)، فإن أساليب المنشئ الفردية لها الأسبقية على القيم من موفر التكوين.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { ObservabilityConfiguration } from '@microsoft/agents-a365-observability';

const configProvider = new ObservabilityConfiguration({
  isObservabilityExporterEnabled: () => true,
  // Set log levels as pipe-separated values (for example, 'info|warn|error')
  observabilityLogLevel: () => 'info|warn|error',
});

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withConfigurationProvider(configProvider)
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

يمكنك تخصيص سلوك المصدر عن طريق تمرير مثيل Agent365ExporterOptions إلى withExporterOptions. هذا الخيار يسمح لك بالتحكم في التجميع والمهلات. لا يغير مسار التصدير.

import {
  ObservabilityManager,
  Agent365ExporterOptions,
} from '@microsoft/agents-a365-observability';
import { ClusterCategory } from '@microsoft/agents-a365-runtime';

const exporterOptions = new Agent365ExporterOptions();
exporterOptions.maxQueueSize = 10;

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withClusterCategory(ClusterCategory.prod)
    .withExporterOptions(exporterOptions)
    .withTokenResolver(tokenResolver)
);

builder.start();

يصف الجدول التالي الخصائص الاختيارية ل Agent365ExporterOptions.

الملكية	الوصف	Default
`useS2SEndpoint`	مهمل ويتم تجاهله. يستخدم Agent 365 SDK 2.0 وما بعده دائمًا مسار S2S، حتى عندما تكون هذه القيمة `false`.	`true` (متجاهل)
`maxQueueSize`	الحد الأقصى لحجم قائمة الانتظار لمعالج الدفعات.	`2048`
`scheduledDelayMilliseconds`	التأخير بالمللي ثانية بين دفعات التصدير.	`5000`
`exporterTimeoutMilliseconds`	المهلة بالمللي ثانية لعملية التصدير بأكملها.	`90000`
`httpRequestTimeoutMilliseconds`	المهلة بالمللي ثانية لكل طلب HTTP فردي إلى الخادم الخلفي.	`30000`
`maxExportBatchSize`	الحد الأقصى لحجم الدفعة لعمليات التصدير.	`512`

يمكنك أيضا توفير مسجل مخصص ينفذ الواجهة ILogger (info, warn, error, event). مرره إلى الباني باستخدام withCustomLogger.

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withCustomLogger({
      info: (message, ...args) => { /* your logging logic */ },
      warn: (message, ...args) => { /* your logging logic */ },
      error: (message, ...args) => { /* your logging logic */ },
      event: (eventName, success, durationMs, message, details) => { /* your logging logic */ }
    })
    .withTokenResolver((agentId, tenantId) => {
      return tokenResolver(agentId, tenantId);
    })
);

builder.start();

تعيين EnableAgent365Exporter إلى true في appsettings.json. في Agent 365 SDK 2.0 وما بعده، يستخدم المُصدِّر دائمًا مسار S2S ويصادق باستخدام مُحدِّد رمز الوصول الخاص بالتطبيق فقط المكوَّن. إذا فعلت المُصدِّر بدون TokenResolver أو ContextualTokenResolver، فإن إنشاء المُصدِّر يفشل.

في Program.cs، أضف Agent365ExporterOptions إلى مجموعة الخدمة. يقوم هذا التغيير بتكوين التفويض الذي يستخدمه مصدر التتبع لاسترداد الرمز المميز.

أضف تبعيات متعلقة بالملاحظة باستخدام AddA365Tracing().

using Microsoft.Agents.A365.Observability.Runtime;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Exporters;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // Return a cached, validated app-only observability token for this agent and tenant.
                var token = await tokenProvider.GetObservabilityTokenAsync(agentId, tenantId);
                return token;
            }
        };
    });

builder.AddA365Tracing();

يمكنك تخصيص سلوك المُصَدِّر عن طريق تمرير مفوض التهيئة ونوع المُصَدِّر إلى AddA365Tracing().

builder.AddA365Tracing(
    configure: tracingBuilder =>
    {
        // Use the builder to add extensions (e.g., WithSemanticKernel(), WithOpenAI())
    },
    agent365ExporterType: Agent365ExporterType.Agent365ExporterAsync
);

يصف الجدول التالي الخصائص الاختيارية ل Agent365ExporterOptions.

الملكية	الوصف	Default
`UseS2SEndpoint`	أُوقِف استخدامه وتجاهله. يستخدم Agent 365 SDK 2.0 وما بعده دائما مسار S2S، حتى عندما تكون هذه القيمة هي `false`.	`false` (متجاهل)
`MaxQueueSize`	الحد الأقصى لحجم قائمة الانتظار لمعالج الدفعات.	`2048`
`ScheduledDelayMilliseconds`	التأخير بالمللي ثانية بين دفعات التصدير.	`5000`
`ExporterTimeoutMilliseconds`	المهلة بالمللي ثانية لعملية التصدير.	`30000`
`MaxExportBatchSize`	الحد الأقصى لحجم الدفعة لعمليات التصدير.	`512`

سمات الأمتعة

يستخدم BaggageBuilder لتعيين المعلومات السياقية التي تتدفق عبر جميع الامتدادات في الطلب. تنفذ مجموعة تطوير البرمجيات (SDK) عملية SpanProcessor تنسخ جميع إدخالات الأعباء غير الفارغة إلى المقاطع الجديدة دون الكتابة فوق السمات الموجودة.

from microsoft_agents_a365.observability.core import BaggageBuilder

with (
    BaggageBuilder()
    .tenant_id("tenant-123")
    .agent_id("agent-456")
    .conversation_id("conv-789")
    .build()
):
    # Any spans started in this context will receive these as attributes
    pass

لتعبئة BaggageBuilder تلقائيًا من TurnContext، استخدم populate المساعد في الحزمة microsoft-agents-a365-observability-hosting. يستخرج هذا المساعد تلقائيا تفاصيل المتصل والوكيل والمستأجر والقناة والمحادثة من النشاط.

from microsoft_agents.hosting.core.turn_context import TurnContext
from microsoft_agents_a365.observability.core import BaggageBuilder
from microsoft_agents_a365.observability.hosting.scope_helpers.populate_baggage import populate

builder = BaggageBuilder()
populate(builder, turn_context)

with builder.build():
    # Baggage is auto-populated from the TurnContext activity
    pass

import { BaggageBuilder } from '@microsoft/agents-a365-observability';

// Create and apply baggage context
const baggageScope = new BaggageBuilder()
  // Core identifiers
  .tenantId('tenant-123')
  .agentId('agent-456')
  .conversationId('conv-789')
  .build();

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values

  // Invoke another agent
  const agentScope = InvokeAgentScope.start(request, scopeDetails, agentDetails);
  // ... agent logic

  // Execute tools
  const toolScope = ExecuteToolScope.start(request, toolDetails, agentDetails);
  // ... tool logic
});

لتعبئة BaggageBuilder تلقائيًا من TurnContext، استخدم fromTurnContext المساعد في الحزمة @microsoft/agents-a365-observability-hosting. يستخرج هذا المساعد تلقائيا تفاصيل المتصل والوكيل والمستأجر والقناة والمحادثة من النشاط.

import { BaggageBuilder } from '@microsoft/agents-a365-observability';
import { BaggageBuilderUtils } from '@microsoft/agents-a365-observability-hosting';

const baggageScope = BaggageBuilderUtils.fromTurnContext(new BaggageBuilder(), context)
  .invokeAgentServer(context.activity.serviceUrl, 3978)
  .build();

await baggageScope.run(async () => {
  // Baggage is auto-populated from the TurnContext activity
});

using Microsoft.Agents.A365.Observability.Runtime.Common;

using var baggageScope = new BaggageBuilder()
    .TenantId("tenant-123")
    .AgentId("agent-456")
    .ConversationId("conv-789")
    .Build();
// Any spans started in this context will receive them as attributes.

لملء BaggageBuilder تلقائيًا من ITurnContext، استخدم طريقة الامتداد FromTurnContext في حزمة Microsoft.Agents.A365.Observability.Hosting. تستخرج هذه الطريقة تلقائيا تفاصيل المتصل والعامل والمستأجر والقناة والمحادثة من النشاط.

using Microsoft.Agents.A365.Observability.Runtime.Common;
using Microsoft.Agents.A365.Observability.Hosting.Extensions;

using var baggageScope = new BaggageBuilder()
    .FromTurnContext(turnContext)
    .Build();

البرامج الوسيطة للأمتعة

إذا كان وكيلك يستخدم حزمة تكامل الاستضافة، فسجل البرامج الوسيطة للأمتعة لملء الأمتعة تلقائيا لكل طلب وارد. تزيل هذه الخطوة الحاجة إلى استدعاء BaggageBuilder يدويا في كل معالج نشاط.

سجل BaggageMiddleware في مجموعة البرامج للمحول الوسيط. يقوم تلقائيًا باستخراج تفاصيل المتصل والوكيل والمستأجر والقناة والمحادثة من كل عنصر وارد TurnContext ويغلف الطلب ضمن نطاق نقل البيانات.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

بدلا من ذلك، استخدم ObservabilityHostingManager لتكوين البرامج الوسيطة للأمتعة جنبا إلى جنب مع ميزات الاستضافة الأخرى:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

options = ObservabilityHostingOptions(enable_baggage=True)
ObservabilityHostingManager.configure(adapter.middleware_set, options)

يتجنب الواجهة البرمجية الوسيطة إعداد المعلومات المصاحبة للردود غير المتزامنة (ContinueConversation الأحداث) لتفادي استبدال المعلومات التي قد تم إعدادها بالفعل في الطلب الأصلي.

قم بتسجيل BaggageMiddleware على المحول. يقوم تلقائيًا باستخراج تفاصيل المتصل والوكيل والمستأجر والقناة والمحادثة من كل عنصر وارد TurnContext ويغلف الطلب ضمن نطاق نقل البيانات.

import { BaggageMiddleware } from '@microsoft/agents-a365-observability-hosting';

// Option 1: Register middleware directly on the adapter
adapter.use(new BaggageMiddleware());

بدلا من ذلك، استخدم ObservabilityHostingManager لتكوين البرامج الوسيطة للأمتعة جنبا إلى جنب مع ميزات الاستضافة الأخرى:

import { ObservabilityHostingManager } from '@microsoft/agents-a365-observability-hosting';

const manager = new ObservabilityHostingManager();
manager.configure(adapter, { enableBaggage: true });

قم بتسجيل BaggageTurnMiddleware على المحول. يقوم تلقائيًا باستخراج تفاصيل المتصل والوكيل والمستأجر والقناة والمحادثة من كل عنصر وارد ITurnContext ويغلف الطلب ضمن نطاق نقل البيانات.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

adapter.Use(new BaggageTurnMiddleware());

إذا كنت بحاجة إلى الأمتعة على مستوى HTTP (على سبيل المثال، لتعيين معرفات المستأجر والوكيل قبل تشغيل مسار Bot Framework)، فقم بتسجيل ObservabilityBaggageMiddleware في البنية الأساسية لبرنامج ربط العمليات التجارية ASP.NET Core باستخدام أسلوب ملحق UseObservabilityRequestContext. يجب توفير دالة محلل تستخرج معرف المستأجر ومعرف العامل من سياق HTTP.

using Microsoft.Agents.A365.Observability.Hosting.Middleware;

app.UseObservabilityRequestContext((httpContext) =>
{
    // Extract tenant and agent IDs from your request context
    var tenantId = GetTenantIdFromContext(httpContext);
    var agentId = GetAgentIdFromContext(httpContext);
    return (tenantId, agentId);
});

محلل الرمز المميز

عند استخدام المُصدِّر Agent 365 في Agent 365 SDK 2.0 وما بعده، وفّر محلّل الرموز الذي يعيد الرمز النهائي لقابلية ملاحظة التطبيق فقط لمثيل الوكيل المُصدِّر. المُصدِّر دائمًا يرسل بيانات تتبع الاستخدام إلى مسار S2S ولا يلجأ إلى المسار المفوض كمسار بديل. لا يحتاج مثيل وكيل مسجل في Agent 365 إلى Agent365.Observability.OtelWrite إذن أو موافقة المسؤول للتصدير عبر هذا المسار.

استخدم تبادل الهوية المدارة الاتحادية (FMI) ذي الخطوتين للحصول على الرمز المميز الخاص بالتطبيق فقط:

احصل على رمز Blueprint client_credentials لـ api://AzureADTokenExchange/.default مع تعيين fmi_path على معرّف عميل مثيل الوكيل.
احصل على رمز agent-instance‏ client_credentials لـ api://9b975845-388f-4429-889e-eab1ef63949c/.default. مرر رمز الخطوة 1 كـ client_assertion، واضبط client_assertion_type على urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

للاطلاع على إعداد المصادقة الكامل، انظر Agent 365-enabled باستخدام S2S. للاطلاع على عمليات التنفيذ الكاملة لخدمات الرمز المميز، راجع عينات Agent 365 لـ Node.js وPython و.NET.

يجب أن يكون محلّل الأسماء لديك:

يُرجع رمزًا خاصًا بالتطبيق فقط لمثيل عامل التصدير والعميل المستأجر. لا تعيد أبدا إثبات المخطط الوسيط، أو رمز المخطط، أو رمز المستخدم، أو رمز OBO.
تحقق من صحة الرمز قبل أن يعيده. قبول idtyp=app. إذا idtyp كان غائبا، اقبل فقط رمزا له مطالبة غير فارغة roles أو مطالبة غير فارغة oid تساوي sub. ارفض الرموز التي لها بيان scp أو قيمة idtyp أخرى، أو الرموز منتهية الصلاحية، أو الرموز التي لا تكون قيمة aud فيها 9b975845-388f-4429-889e-eab1ef63949c أو api://9b975845-388f-4429-889e-eab1ef63949c.
احتفظ بالرمز مؤقتا وقم بتحديثه قبل انتهاء صلاحيته. يقوم المصدر باستدعاء المُحدِّد مرة واحدة لكل هوية مستأجر ولكل هوية وكيل في كل دفعة تصدير.

ملحوظة

الانتقال من SDK 1.x: SDK 2.0 يزيل تبادل الرموز المفوض لتصدير المرئية. استبدل رمز التوكن المفوَّض في الوكيل الخاص بك بمُحلِّل خاص بالتطبيق فقط، كما هو موضح في الأمثلة التالية. الوكلاء الذين يبقون على SDK 1.x ويُجرون التصدير عبر المسار المفوض لا يزالون بحاجة إلى الإذن المفوض Agent365.Observability.OtelWrite وموافقة المسؤول. الأمر a365 setup all لا يضبط هذا الإذن لوكلاء Blueprint. لمنح هذا الإذن، راجع امنح الإذن.

أجرِ مكالمة AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, acquire_app_only_obs_token) من token_resolver. تمرر ذاكرة التخزين المؤقت نطاق إمكانية المراقبة /.default إلى استدعاء acquisition callback الخاص بك وتُعيد الرمز المميز المخزن مؤقتًا.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import AgenticTokenCache

cache = AgenticTokenCache()

async def acquire_app_only_obs_token(
    agent_id: str,
    tenant_id: str,
    scopes: list[str],
) -> str:
    # Run the FMI exchange described earlier, validate the token, and return it.
    return "<app-only-observability-token>"

async def token_resolver(agent_id: str, tenant_id: str) -> str:
    return await cache.refresh_observability_token(
        agent_id, tenant_id, acquire_app_only_obs_token
    )

configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_resolver,
)

يدعم Python أيضًا مُحلِّل أسماء متزامنًا يعيد رمزًا من ذاكرة تخزين مؤقت آمنة للخيوط. تستخدم عينات Agent 365 هذا النمط، مما يتجنب قيود تشغيل محلل غير متزامن على خيط المصدّر.

للانتقال من SDK 1.x، قم بإزالة النداء AGENT_APP.auth.exchange_token الذي طلب نطاق إمكانية الملاحظة والاستدعاء AgenticTokenCache.register_observability الذي مرر AgenticTokenStruct. في SDK 2.0، register_observability هو no-op مهمَل.

استخدم withTokenResolver مع AgenticTokenCacheInstance.RefreshObservabilityToken(agentId, tenantId, acquireAppOnlyObsToken). تستلم دالة الاستدعاء acquisition callback ‏(agentId, tenantId, scopes)‎ وتعيد رمز قابلية الملاحظة النهائي الخاص بالتطبيق فقط. اقرأ الرمز المخزن مؤقتًا بـAgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId).

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { AgenticTokenCacheInstance } from '@microsoft/agents-a365-observability-hosting';

async function acquireAppOnlyObsToken(
  agentId: string,
  tenantId: string,
  scopes: readonly string[]
): Promise<string> {
  // Run the FMI exchange described earlier, validate the token, and return it.
  return "<app-only-observability-token>";
}

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver(async (agentId, tenantId) => {
      await AgenticTokenCacheInstance.RefreshObservabilityToken(
        agentId, tenantId, acquireAppOnlyObsToken
      );
      return AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId);
    })
);

builder.start();

للانتقال من SDK 1.x، قم بإزالة النداء agentApplication.authorization.exchangeToken الذي طلب نطاق قابلية المراقبة، واستبدل RefreshObservabilityToken(agentId, tenantId, context, authorization, scopes) بنموذج المُحلِّل في المثال. تزيل SDK 2.0 التحميل الزائد المفوض: يحصل مستدعو TypeScript على خطأ في التجميع، ويحصل المستدعون غير المعرّفة أنواعهم على رسالة خطأ تُسجَّل مرة واحدة ولا يحصلون على رمز مميز.

استخدم AddAgenticTracingExporter() لتسجيل IExporterTokenCache<ObservabilityTokenResolver> وخيارات المُصدِّر التي تقرأ الرموز من الذاكرة المؤقتة.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

في تطبيق الوكيل، سجّل محلّلًا خاصًا بالتطبيق فقط للوكيل والعميل المستأجر عن طريق استدعاء RegisterObservability(agentId, tenantId, resolver, scopes). يُعتدّ بأول تسجيل لوكيل ومستأجر.

using Microsoft.Agents.A365.Observability.Hosting.Caching;
using Microsoft.Agents.A365.Observability.Runtime.Common;
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using System.Threading;
using System.Threading.Tasks;

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<ObservabilityTokenResolver> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<ObservabilityTokenResolver> agentTokenCache)
        : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var agentId = turnContext.Activity.Recipient.AgenticAppId;
        var tenantId = turnContext.Activity.Recipient.TenantId;

        _agentTokenCache.RegisterObservability(
            agentId,
            tenantId,
            AcquireAppOnlyObservabilityTokenAsync,
            EnvironmentUtils.GetObservabilityAuthenticationScope());

        using var baggageScope = new BaggageBuilder()
            .TenantId(tenantId)
            .AgentId(agentId)
            .Build();

        // Handle the message.
    }

    private static Task<string?> AcquireAppOnlyObservabilityTokenAsync(
        string agentId,
        string tenantId,
        string[] observabilityScopes)
    {
        // Run the FMI exchange described earlier, validate the token, and return it.
        return Task.FromResult<string?>("<app-only-observability-token>");
    }
}

إذا كنت تدير AgenticTokenCache مثيلاً مباشرة، فاستدعِ RefreshObservabilityToken(agentId, tenantId, resolver) لاستخدام نطاق الملاحظة الافتراضي، أو استدعِ RefreshObservabilityToken(agentId, tenantId, resolver, scopes) لتمرير النطاقات بشكل صريح.

للانتقال من SDK 1.x، استبدل IExporterTokenCache<AgenticTokenStruct> والنداء RegisterObservability الذي مرّر AgenticTokenStruct بمُحلِّل التطبيق فقط المستخدم في المثال. لا تستخدم ExchangeTurnTokenAsync لتصدير بيانات المراقبة. في SDK 2.0، تصبح زيادة التحميل للتسجيل AgenticTokenStruct قديمة وتنتج خطأ تجميع.

التجهيز التلقائي

يستمع التنميط التلقائي إلى إشارات القياس عن بعد الخاصة بالأطر الوكيلة (SDKs) بشكل تلقائي للتتبعات، ثم يحيلها إلى خدمة Agent 365 للرصد. تلغي هذه الميزة الحاجة للمطورين لكتابة كود المراقبة يدويا، وتبسط الإعداد، وتضمن تتبع الأداء المتسق.

Important

تملأ الأجهزة التلقائية سمات OTel القياسية فقط. يجب إضافة سمات خاصة Microsoft من خلال BaggageBuilder. لمعرفة السمات المفقودة، تحقق من صحة إخراج نطاق وحدة التحكم مقابل سجلات المتجر لمجموعة diff.

تدعم عدة مجموعات تطوير ومنصات تقنية القياس التلقائي:

المنصة	SDKs / أطر العمل المدعومة
.NET	نواة دلالية، OpenAI، Agent Framework
Python	نواة دلالية، OpenAI، Agent Framework، LangChain
Node.js	OpenAI،لانغتشين

ملحوظة

يختلف دعم الأجهزة التلقائية حسب النظام الأساسي وتنفيذ SDK.

النواة الدلالية

يتطلب القياس التلقائي استخدام منشئ baggage. قم بتعيين معرف الوكيل ومعرف المستأجر باستخدام BaggageBuilder.

تثبيت الحزمة.

pip install microsoft-agents-a365-observability-extensions-semantic-kernel

تهيئة قدرات المراقبة.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.semantickernel.trace_instrumentor import SemanticKernelInstrumentor

# Configure observability
configure(
    service_name="my-semantic-kernel-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = SemanticKernelInstrumentor()
instrumentor.instrument()

# Your Semantic Kernel code is now automatically traced

إضافة التبعيات إلى مجموعة الخدمات.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;

builder.AddA365Tracing(configure: config => config.WithSemanticKernel());

قم بتعيين AgentId و TenantId باستخدام BaggageBuilder. تأكد من أن المعرف الذي تستخدمه عند إنشاء ال ChatCompletionAgent يتطابق مع معرف الوكيل الذي تمرره إليه BaggageBuilder.

using Microsoft.Agents.A365.Observability.Extensions.SemanticKernel;
using Microsoft.Agents.A365.Observability.Runtime.Common;
public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      var chatCompletionAgent = new ChatCompletionAgent
      {
          // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. Should match above.
          Id = <your-agent-id>,
          ...
      };
    }
}

OpenAI

يتطلب القياس التلقائي استخدام منشئ Baggage. قم بتعيين معرف الوكيل ومعرف المستأجر باستخدام BaggageBuilder.

تثبيت الحزمة.

pip install microsoft-agents-a365-observability-extensions-openai

تهيئة قدرات المراقبة.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.openai import OpenAIAgentsTraceInstrumentor

# Configure observability
configure(
    service_name="my-openai-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
instrumentor = OpenAIAgentsTraceInstrumentor()
instrumentor.instrument()

# Your OpenAI Agents code is now automatically traced

تثبيت الحزمة.

npm install @microsoft/agents-a365-observability-extensions-openai

تهيئة قدرات المراقبة.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { OpenAIAgentsTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-openai';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

// Create and enable the instrumentor
const instrumentor = new OpenAIAgentsTraceInstrumentor({
  enabled: true,
  tracerName: 'openai-agents-tracer',
  tracerVersion: '1.0.0'
});

sdk.start();

instrumentor.enable();

إضافة التبعيات إلى مجموعة الخدمات.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;

builder.AddA365Tracing(configure: config => config.WithOpenAI());

قم بتعيين AgentId و TenantId باستخدام BaggageBuilder. بالنسبة لاستدعاءات الأدوات، ابدأ تتبُّعًا باستخدام Trace() على مثيل ChatToolCall.

using Microsoft.Agents.A365.Observability.Extensions.OpenAI;
using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
      
      // NOTE: This will be the agent and tenant ID with which the TokenResolver delegate will be invoked. 
      using var scope = chatToolCall.Trace(agentId: <your-agent-id>, <your-tenant-id>);
    }
}

إطار عمل الوكيل

يتطلب التجهيز التلقائي استخدام منشئ الـ baggage. قم بتعيين معرف الوكيل ومعرف المستأجر باستخدام BaggageBuilder.

تثبيت الحزمة.

pip install microsoft-agents-a365-observability-extensions-agent-framework

تهيئة قدرات المراقبة.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.extensions.agentframework import (
    AgentFrameworkInstrumentor,
)

# Configure observability
configure(
    service_name="AgentFrameworkTracingWithAzureOpenAI",
    service_namespace="AgentFrameworkTesting",
)

# Enable auto-instrumentation
AgentFrameworkInstrumentor().instrument()

إضافة التبعيات إلى مجموعة الخدمات.

using Microsoft.Agents.A365.Observability.Extensions.AgentFramework;

builder.AddA365Tracing(configure: config => config.WithAgentFramework());

قم بتعيين AgentId و TenantId باستخدام BaggageBuilder.

using Microsoft.Agents.A365.Observability.Runtime.Common;

public class MyAgent : AgentApplication
{
    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
      using var baggageScope = new BaggageBuilder()
          .AgentId(<your-agent-id>) // NOTE: This will be the agent ID with which the TokenResolver delegate is invoked. 
          .TenantId(<your-tenant-id>) // NOTE: This will be the tenant ID with which the TokenResolver delegate is invoked.
          .Build();
    }
}

إطار عمل LangChain

ملحوظة

يدعم التجهيز التلقائي لأطر عمل LangChain أيضًا كلاً من LangGraph وDeep Agents. يلتقط نفس الملحق تلقائيا بيانات تتبع الاستخدام للعوامل المبنيين باستخدام أي من هذه الأطر.

تتطلب الأجهزة الآلية اِسْتِخْدَام منشئ الأمتعة. قم بتعيين معرف الوكيل ومعرف المستأجر باستخدام BaggageBuilder.

تثبيت الحزمة.

pip install microsoft-agents-a365-observability-extensions-langchain

تهيئة قدرات المراقبة.

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.langchain import CustomLangChainInstrumentor

# Configure observability
configure(
    service_name="my-langchain-agent",
    service_namespace="ai.agents"
)

# Enable auto-instrumentation
CustomLangChainInstrumentor()

# Your LangChain code is now automatically traced

تثبيت الحزمة.

npm install @microsoft/agents-a365-observability-extensions-langchain

تهيئة قدرات المراقبة.

import { ObservabilityManager } from '@microsoft/agents-a365-observability';
import { LangChainTraceInstrumentor } from '@microsoft/agents-a365-observability-extensions-langchain';
import * as LangChainCallbacks from '@langchain/core/callbacks/manager';

// Configure observability first
const sdk = ObservabilityManager.configure((builder) =>
  builder
    .withService('My Agent Service', '1.0.0')
);

sdk.start();

// Enable LangChain auto-instrumentation
LangChainTraceInstrumentor.instrument(LangChainCallbacks);

// Your LangChain code is now automatically traced

الأدوات اليدوية

استخدم SDK قابلية المراقبة لـ Agent 365 لفهم العمل الداخلي للوكيل البرمجي. يوفر SDK النطاقات التي يمكنك بدء تشغيلها: InvokeAgentScopeو ExecuteToolScopeInferenceScopeو و.OutputScope

استدعاء الوكيل

استخدم هذا النطاق في بداية عملية وكيلك. باستخدام نطاق وكيل الاستدعاء، يمكنك التقاط خصائص مثل الوكيل الحالي الذي يتم استدعاؤه، وبيانات مستخدم الوكيل، والمزيد.

from microsoft_agents_a365.observability.core import (
    InvokeAgentScope,
    InvokeAgentScopeDetails,
    AgentDetails,
    CallerDetails,
    UserDetails,
    Channel,
    Request,
    ServiceEndpoint,
)

agent_details = AgentDetails(
    agent_id="agent-456",
    agent_name="My Agent",
    agent_description="An AI agent powered by Azure OpenAI",
    agentic_user_id="auid-123",
    agentic_user_email="agent@contoso.com",
    agent_blueprint_id="blueprint-789",
    tenant_id="tenant-123",
)

scope_details = InvokeAgentScopeDetails(
    endpoint=ServiceEndpoint(hostname="myagent.contoso.com", port=443),
)

request = Request(
    content="User asks a question",
    session_id="session-42",
    conversation_id="conv-xyz",
    channel=Channel(name="msteams"),
)

caller_details = CallerDetails(
    user_details=UserDetails(
        user_id="user-123",
        user_email="jane.doe@contoso.com",
        user_name="Jane Doe",
    ),
)

with InvokeAgentScope.start(request, scope_details, agent_details, caller_details):
    # Perform agent invocation logic
    response = call_agent(...)

import {
  InvokeAgentScope,
  InvokeAgentScopeDetails,
  AgentDetails,
  CallerDetails,
  UserDetails,
  Channel,
  Request,
  ServiceEndpoint,
} from '@microsoft/agents-a365-observability';

// Use the same agentDetails instance across all scopes in a request
const agentDetails: AgentDetails = {
  agentId: 'agent-456',
  agentName: 'Email Assistant',
  agentDescription: 'An AI agent powered by Azure OpenAI',
  agentAuid: 'auid-123',
  agentEmail: 'agent@contoso.com',
  agentBlueprintId: 'blueprint-789',
  tenantId: 'tenant-123',
};

const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

// Use the same request instance across all scopes in a request
const request: Request = {
  content: 'Please help me organize my emails',
  sessionId: 'session-42',
  conversationId: 'conv-xyz',
  channel: { name: 'msteams' } as Channel,
};

// Optional: Caller details (human user, or agent-to-agent)
const callerDetails: CallerDetails = {
  userDetails: {
    userId: 'user-123',
    userEmail: 'jane.doe@contoso.com',
    userName: 'Jane Doe',
  } as UserDetails,
};

const scope = InvokeAgentScope.start(request, scopeDetails, agentDetails, callerDetails);

try {
  await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Please help me organize my emails', 'Focus on urgent items']);

    // Your agent invocation logic here
    const response = await invokeAgent(request.content);

    // Record output messages
    scope.recordOutputMessages(['I found 15 urgent emails', 'Here is your organized inbox']);
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

إذا كان وكيلك يستخدم الحزمة @microsoft/agents-a365-observability-hosting ، يمكنك استخدام ScopeUtils.populateInvokeAgentScopeFromTurnContext لإنشاء النطاق مع تفاصيل العامل وتفاصيل المتصل ومعلومات القناة المشتقة تلقائيا من TurnContext.

import { InvokeAgentScopeDetails, AgentDetails, ServiceEndpoint } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const agentDetails: AgentDetails = { agentId: 'agent-456' };
const scopeDetails: InvokeAgentScopeDetails = {
  endpoint: { host: 'myagent.contoso.com', port: 443 } as ServiceEndpoint,
};

const scope = ScopeUtils.populateInvokeAgentScopeFromTurnContext(
  agentDetails,
  scopeDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    // Agent details, caller details, and channel are auto-populated from context
    const response = await invokeAgent(context.activity.text);
    scope.recordOutputMessages([response]);
  });
} finally {
  scope.dispose();
}

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

public class MyAgent
{
    public async Task<AgentResponse> ProcessUserRequest(string userInput)
    {
        var agentDetails = new AgentDetails(
            agentId: "agent-456",
            agentName: "MyAgent",
            agentDescription: "Handles user requests.",
            agenticUserId: "auid-123",
            agenticUserEmail: "agent@contoso.com",
            agentBlueprintId: "blueprint-789",
            tenantId: "tenant-123"
        );

        var scopeDetails = new InvokeAgentScopeDetails(
            endpoint: new Uri("https://myagent.contoso.com")
        );

        var request = new Request(
            content: userInput,
            sessionId: "session-abc",
            channel: new Channel("msteams"),
            conversationId: "conv-xyz"
        );

        var callerDetails = new CallerDetails(
            userDetails: new UserDetails(
                userId: "user-123",
                userEmail: "jane.doe@contoso.com",
                userName: "Jane Doe"
            )
        );

        // Start the scope
        using var scope = InvokeAgentScope.Start(
            request: request,
            scopeDetails: scopeDetails,
            agentDetails: agentDetails,
            callerDetails: callerDetails
        );

        // Record input messages
        scope.RecordInputMessages(new[] { userInput });

        // ... your agent logic here ...

        var output = $"Processed: {userInput}";
        scope.RecordOutputMessages(new[] { output });

        return new AgentResponse { Content = output };
    }
}

public class AgentResponse
{
    public string Content { get; set; }
}

تنفيذ الأدوات

الأمثلة التالية توضح كيفية إضافة تتبع قابلية الملاحظة إلى تنفيذ أداة وكيلك. يلتقط هذا التتبع بيانات التليمترية لأغراض المراقبة والتدقيق.

from microsoft_agents_a365.observability.core import (
    ExecuteToolScope,
    ToolCallDetails,
    Request,
    ServiceEndpoint,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

tool_details = ToolCallDetails(
    tool_name="summarize",
    tool_type="function",
    tool_call_id="tc-001",
    arguments="{'text': '...'}",
    description="Summarize provided text",
    endpoint=ServiceEndpoint(hostname="tools.contoso.com", port=8080),
)

with ExecuteToolScope.start(request, tool_details, agent_details) as scope:
    result = run_tool(tool_details)
    scope.record_response(result)

import { ExecuteToolScope, ToolCallDetails } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com', limit: 10 }),
  toolCallId: 'tool-call-456',
  description: 'Search emails by criteria',
  toolType: 'function',
  endpoint: {
    host: 'tools.contoso.com',
    port: 8080,  // Will be recorded since not 443
    protocol: 'https'
  },
};

const scope = ExecuteToolScope.start(request, toolDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Execute the tool
    const result = await searchEmails(toolDetails.arguments);

    // Record the tool execution result
    scope.recordResponse(result);

    return result;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

إذا كان عاملك يستخدم الحزمة @microsoft/agents-a365-observability-hosting ، فاستخدم ScopeUtils.populateExecuteToolScopeFromTurnContext لإنشاء النطاق بتفاصيل العامل المشتقة تلقائيا من TurnContext.

import { ToolCallDetails } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const toolDetails: ToolCallDetails = {
  toolName: 'email-search',
  arguments: JSON.stringify({ query: 'from:boss@company.com' }),
  toolCallId: 'tool-call-456',
  toolType: 'function',
};

const scope = ScopeUtils.populateExecuteToolScopeFromTurnContext(
  toolDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const result = await searchEmails(toolDetails.arguments);
    scope.recordResponse(JSON.stringify(result));
  });
} finally {
  scope.dispose();
}

using System;
using System.Threading.Tasks;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var toolCallDetails = new ToolCallDetails(
    toolName: "summarize",
    arguments: "{\"text\": \"...\"}",
    toolCallId: "tc-001",
    description: "Summarize provided text",
    toolType: "function",
    endpoint: new Uri("https://tools.contoso.com:8080")
);

using var scope = ExecuteToolScope.Start(
    request: request,
    details: toolCallDetails,
    agentDetails: agentDetails
);

// ... your tool logic here ...

scope.RecordResponse("{\"summary\": \"The text was summarized.\"}");

استدلال

تظهر الأمثلة التالية كيفية تجهيز استدعاءات استدلال النموذج بالذكاء الاصطناعي بتتبع إمكانية المراقبة لالتقاط استخدام الرموز المميزة وتفاصيل النموذج والبيانات الوصفية للاستجابة.

from microsoft_agents_a365.observability.core import (
    InferenceScope,
    InferenceCallDetails,
    InferenceOperationType,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

inference_details = InferenceCallDetails(
    operationName=InferenceOperationType.CHAT,
    model="gpt-4o-mini",
    providerName="azure-openai",
    inputTokens=123,
    outputTokens=456,
    finishReasons=["stop"],
)

with InferenceScope.start(request, inference_details, agent_details) as scope:
    completion = call_llm(...)
    scope.record_output_messages([completion.text])
    scope.record_input_tokens(completion.usage.input_tokens)
    scope.record_output_tokens(completion.usage.output_tokens)

import { InferenceScope, InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = InferenceScope.start(request, inferenceDetails, agentDetails);

try {
  return await scope.withActiveSpanAsync(async () => {
    // Record input messages
    scope.recordInputMessages(['Summarize the following emails for me...']);

    // Call the LLM
    const response = await callLLM();

    // Record detailed telemetry with granular methods
    scope.recordOutputMessages(['Here is your email summary...']);
    scope.recordInputTokens(145);
    scope.recordOutputTokens(82);
    scope.recordFinishReasons(['stop']);

    return response.text;
  });
} catch (error) {
  scope.recordError(error as Error);
  throw error;
} finally {
  scope.dispose();
}

إذا كان العامل الخاص بك يستخدم الحزمة @microsoft/agents-a365-observability-hosting ، يمكنك استخدام ScopeUtils.populateInferenceScopeFromTurnContext لإنشاء النطاق مع تفاصيل العامل المشتقة تلقائيا من TurnContext.

import { InferenceDetails, InferenceOperationType } from '@microsoft/agents-a365-observability';
import { ScopeUtils } from '@microsoft/agents-a365-observability-hosting';

const inferenceDetails: InferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4o-mini',
  providerName: 'azure-openai',
};

const scope = ScopeUtils.populateInferenceScopeFromTurnContext(
  inferenceDetails,
  context,     // TurnContext
  authToken    // authentication token string
);

try {
  await scope.withActiveSpanAsync(async () => {
    const response = await callLLM();
    scope.recordOutputMessages([response.text]);
    scope.recordInputTokens(response.usage.inputTokens);
    scope.recordOutputTokens(response.usage.outputTokens);
  });
} finally {
  scope.dispose();
}

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

var inferenceDetails = new InferenceCallDetails(
    operationName: InferenceOperationType.Chat,
    model: "gpt-4o-mini",
    providerName: "Azure OpenAI",
    inputTokens: 123,
    outputTokens: 456,
    finishReasons: new[] { "stop" }
);

using var scope = InferenceScope.Start(
    request: request,
    details: inferenceDetails,
    agentDetails: agentDetails
);

// ... your inference logic here ...

scope.RecordOutputMessages(new[] { "AI response message" });
scope.RecordInputTokens(123);
scope.RecordOutputTokens(456);

الإخرَاج

استخدم هذا النطاق للسيناريوهات غير المتزامنة حيث InvokeAgentScopeExecuteToolScope، أو ، أو InferenceScope لا يمكن التقاط بيانات الإخراج بشكل متزامن. ابدأ OutputScope كامتداد فرعي لتسجيل رسائل الإخراج النهائية بعد انتهاء النطاق الأصل.

from microsoft_agents_a365.observability.core import (
    OutputScope,
    Response,
    SpanDetails,
)

# Use the same agent_details and request instances from the InvokeAgentScope example above

# Get the parent context from the originating scope
parent_context = invoke_scope.get_context()

response = Response(messages=["Here is your organized inbox with 15 urgent emails."])

with OutputScope.start(
    request,
    response,
    agent_details,
    span_details=SpanDetails(parent_context=parent_context),
):
    # Output messages are recorded automatically from the response
    pass

import { OutputScope, OutputResponse, SpanDetails } from '@microsoft/agents-a365-observability';

// Use the same agentDetails and request instances from the InvokeAgentScope example above

// Get the parent context from the originating scope
const parentContext = invokeScope.getSpanContext();

const response: OutputResponse = {
  messages: ['Here is your organized inbox with 15 urgent emails.'],
};

const scope = OutputScope.start(
  request,
  response,
  agentDetails,
  undefined, // userDetails
  { parentContext } as SpanDetails
);

// Output messages are recorded automatically from the response
scope.dispose();

using Microsoft.Agents.A365.Observability.Runtime.Tracing.Contracts;
using Microsoft.Agents.A365.Observability.Runtime.Tracing.Scopes;

// Use the same agentDetails and request instances from the InvokeAgentScope example above

// Get the parent context from the originating scope
var parentContext = invokeScope.GetActivityContext();

var response = new Response(new[] { "Here is your organized inbox with 15 urgent emails." });

using var scope = OutputScope.Start(
    request: request,
    response: response,
    agentDetails: agentDetails,
    spanDetails: new SpanDetails(parentContext: parentContext)
);
// Output messages are recorded automatically from the response

التحقق محليا

للتحقق من أنك دمجمت بنجاح مع SDK قابلية الملاحظة، افحص سجلات الكونسول التي يولدها وكيلك والسجلات من SDK قابلية الملاحظة.

قم بتعيين متغير البيئة ENABLE_A365_OBSERVABILITY_EXPORTER الى false. هذا الإعداد يصدر (traces) إلى وحدة التحكم.

للتحقيق في فشل التصدير، قم بتمكين التسجيل المطول عن طريق الإعداد ENABLE_A365_OBSERVABILITY_EXPORTER إلى true وتكوين تسجيل تتبع الأخطاء في بدء تشغيل التطبيق الخاص بك:

import logging

logging.basicConfig(level=logging.DEBUG)
logging.getLogger("microsoft_agents_a365.observability.core").setLevel(logging.DEBUG)

# Or target only the exporter:
logging.getLogger(
    "microsoft_agents_a365.observability.core.exporters.agent365_exporter"
).setLevel(logging.DEBUG)

رسائل السجل الرئيسية:

DEBUG  Token resolved for agent {agentId} tenant {tenantId}
DEBUG  Exporting {n} spans to {url}
DEBUG  HTTP 200 - correlation ID: abc-123
ERROR  Token resolution failed: {error}
ERROR  HTTP 401 exporting spans - correlation ID: abc-123
INFO   No spans with tenant/agent identity found; nothing exported.

قم بتعيين متغير البيئة ENABLE_A365_OBSERVABILITY_EXPORTER الى false. هذا الإعداد يصدر (traces) إلى وحدة التحكم.

للتحقيق في حالات فشل التصدير، قم بتعيين متغيرات البيئة في .env أو shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

راجع إخراج وحدة التحكم لرسائل مماثلة لـ:

[INFO]  [Agent365Exporter] Exporting 245 spans
[INFO]  [Agent365Exporter] Partitioned into 3 identity groups (2 spans skipped)
[INFO]  [Agent365Exporter] Token resolved successfully via tokenResolver
[EVENT] export-group succeeded in 98ms {"tenantId":"...","agentId":"...","correlationId":"abc-123"}
[ERROR] [Agent365Exporter] Failed with status 401, correlation ID: abc-123
[WARN]  export-partition-span-missing-identity: 5 spans skipped due to missing tenant or agent ID

اختياريا، استخدم مسجلا مخصصا لالتقاط أحداث التصدير إلى ملف:

import { setLogger, ExporterEventNames } from '@microsoft/agents-a365-observability';

setLogger({
  info: (msg, ...args) => myLogger.info(msg, ...args),
  warn: (msg, ...args) => myLogger.warn(msg, ...args),
  error: (msg, ...args) => myLogger.error(msg, ...args),
  event: (eventType: ExporterEventNames, isSuccess: boolean, durationMs: number,
          message?: string, details?: Record<string, string>) => {
    myLogger.info({ eventType, isSuccess, durationMs, message, ...details });
  }
});

تعيين EnableAgent365Exporter إلى false في appsettings.json. هذا الإعداد يصدر (traces) إلى وحدة التحكم.

للتحقيق في حالات فشل التصدير، قم بتكوين تسجيل الدخول المطول في appsettings.json:

{
  "EnableAgent365Exporter": "True",
  "Logging": {
    "LogLevel": {
      "Microsoft.Agents.A365.Observability": "Debug"
    }
  }
}

أو تعيين متغيرات البيئة:

EnableAgent365Exporter=True
A365_OBSERVABILITY_DOMAIN_OVERRIDE=https://your-test-endpoint.example.com
A365_OBSERVABILITY_SCOPE_OVERRIDE=https://api.powerplatform.com/.default

رسائل السجل الرئيسية:

info: Agent365ExporterCore: Obtained token for agent {agentId} tenant {tenantId}.
info: Agent365ExporterCore: Sending {count} spans to {requestUri} for agent {agentId} tenant {tenantId}.
info: Agent365ExporterCore: HTTP {statusCode} exporting spans. 'x-ms-correlation-id': '{correlationId}'.
error: Agent365Exporter: Exception exporting spans: {exception}
warn: Agent365ExporterCore: No token obtained for agent {agentId} tenant {tenantId}. Skipping export.

ملحوظة

إذا لم تقم بتسجيل ILoggerFactory في DI، فإن المصدر يعود تلقائيًا إلى مدوّن أحداث وحدة التحكم.

عرض السجلات المصدرة

لعرض القياس عن بُعد للوكلاء في Microsoft Purview أو Microsoft Defender، تأكد من استيفاء المتطلبات التالية:

Microsoft Purview: يجب تشغيل التدقيق لمؤسستك. للحصول على الإرشادات، راجع تشغيل التدقيق أو إيقاف تشغيله.
Microsoft Defender: يجب تكوين التتبع المتقدم للوصول إلى الجدول CloudAppEvents. للحصول على التفاصيل، راجع جدول CloudAppEvents في مخطط التتبع المتقدم.

التحقق من جاهزية النشر في المتجر

Important

للتحقق من صحة المتجر بنجاح، يجب على الوكيل تنفيذ النطاقات InvokeAgentScope, InferenceScope, وExecuteToolScope. هذه النطاقات الثلاثة مطلوبة للنشر.

قبل النشر، استخدم سجلات وحدة التحكم للتحقق من صحة تكامل إمكانية المراقبة للعامل عن طريق تنفيذ invoke agentexecute toolinferenceالنطاقات المطلوبة و.output ثم قارن سجلات وكيلك مع قوائم السمات التالية للتحقق من وجود جميع السمات المطلوبة. التقط السمات على كل منظار أو من خلال أداة بناء الأمتعة، وأضف سمات اختيارية حسب تقديرك.

لمزيد من المعلومات حول متطلبات النشر في المتجر، راجع إرشادات التحقق من صحة المتجر.

`InvokeAgentScope` سمات

تلخص القائمة التالية سمات القياس عن بعد المطلوبة والاختيارية المسجلة عند بدء InvokeAgentScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "microsoft.a365.caller.agent.blueprint.id": "Optional",
        "microsoft.a365.caller.agent.id": "Optional",
        "microsoft.a365.caller.agent.name": "Optional",
        "microsoft.a365.caller.agent.platform.id": "Optional",
        "microsoft.a365.caller.agent.user.email": "Optional",
        "microsoft.a365.caller.agent.user.id": "Optional",
        "microsoft.a365.caller.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "server.address": "Required",
        "server.port": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

`ExecuteToolScope` سمات

تلخص القائمة التالية سمات القياس عن بعد المطلوبة والاختيارية المسجلة عند بدء ExecuteToolScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.tool.call.arguments": "Required",
        "gen_ai.tool.call.id": "Required",
        "gen_ai.tool.call.result": "Required",
        "gen_ai.tool.description": "Optional",
        "gen_ai.tool.name": "Required",
        "gen_ai.tool.type": "Required",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

`InferenceScope` سمات

تلخص القائمة التالية سمات القياس عن بعد المطلوبة والاختيارية المسجلة عند بدء InferenceScope.

"attributes": {
        "error.type": "Optional",
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.a365.agent.thought.process": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "gen_ai.provider.name": "Required",
        "gen_ai.request.model": "Required",
        "gen_ai.response.finish_reasons": "Optional",
        "gen_ai.usage.input_tokens": "Optional",
        "gen_ai.usage.output_tokens": "Optional",
        "server.address": "Optional",
        "server.port": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.session.id": "Optional",
        "microsoft.tenant.id": "Required"
    }

`OutputScope` سمات

تلخص القائمة التالية سمات القياس عن بعد المطلوبة والاختيارية المسجلة عند بدء OutputScope. استخدم هذا النطاق للسيناريوهات غير المتزامنة حيث لا يمكن للنطاق الأصل التقاط بيانات الإخراج بشكل متزامن.

"attributes": {
        "microsoft.a365.agent.blueprint.id": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "microsoft.a365.agent.platform.id": "Optional",
        "microsoft.agent.user.email": "Required",
        "microsoft.agent.user.id": "Required",
        "gen_ai.agent.version": "Optional",
        "client.address": "Required",
        "user.id": "Required",
        "user.name": "Optional",
        "user.email": "Required",
        "microsoft.channel.link": "Optional",
        "microsoft.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "microsoft.conversation.item.link": "Optional",
        "gen_ai.operation.name": "Required",
        "gen_ai.output.messages": "Required",
        "microsoft.session.id": "Optional",
        "microsoft.session.description": "Optional",
        "microsoft.tenant.id": "Required"
    }

اختبر وكيلك بقدرات المراقبة

بعد تنفيذ إمكانية الملاحظة في وكيلك، اختبره للتأكد من أنه يلتقط البيانات عن بعد بشكل صحيح. اتبع دليل الاختبار لإعداد بيئتك. بعد ذلك، ركز بشكل أساسي على قسم View observability logs للتحقق من أن تنفيذ إمكانية المراقبة يعمل كما هو متوقع.

التحقق:

انتقل إلى: https://admin.cloud.microsoft/#/agents/all
اختر نشاط وكيلك >
ترى جلسات العمل ومكالمات الأدوات

استكشاف الأخطاء وإصلاحها

يصف هذا القسم المشكلات الشائعة عند تنفيذ واستخدام قابلية الملاحظة.

المشكلة	الوصف
لا تظهر بيانات إمكانية المراقبة	لا تظهر أي بيانات قياس عن بُعد لأنه لم يتم تمكين التصدير، أو لأن التكوين غير صحيح، أو لأن تحليل الرمز المميز فشل.
معرف المستأجر المفقود أو معرف العامل - تم تخطي الامتدادات	تُسقَط النطاقات قبل التصدير عندما تكون سمات الهوية المطلوبة للتقسيم مفقودة.
فشل حل الرمز المميز - تصدير تم تخطيه أو غير مصرح به	يفشل التصدير عندما لا يعيد مُحلِّل المرجع أي رمز أو يواجه استثناءً.
HTTP 401 غير مصرح به	تنجح المصادقة من الناحية التركيبية ولكن الرمز المميز غير صالح للاستيعاب بسبب النطاق أو النوع أو انتهاء الصلاحية.
HTTP 403 ممنوع	يتم رفض الوصول بسبب ثغرات في ترخيص المستأجر، أو فقدان تسجيل Agent 365، أو فقدان إذن قابلية الملاحظة إذا كان مطلوبا.
HTTP 403 ممنوع - عدم تطابق معرف العامل	يتم رفض الطلب عندما لا تتطابق هوية العامل في عنوان URL مع الهوية الممثلة بالرمز المميز.
أخطاء HTTP 429 أو 5xx - أخطاء عابرة	يؤدي التقييد المؤقت أو حالات الفشل من جانب الخدمة إلى مقاطعة التصدير وقد يتطلب ضبطا لإعادة المحاولة.
مهلة التصدير	تتجاوز دفعات القياس عن بُعد نوافذ المهلة المحددة بسبب زمن انتقال الشبكة أو بطء استجابة نقطة النهاية.
ينجح التصدير ولكن بيانات تتبع الاستخدام لا تظهر في Defender أو Purview	يكتمل الاستيراد، ولكن يتأخر ظهور البيانات في المراحل اللاحقة أو يُمنع بسبب المتطلبات الأساسية للمنتج.

Tip

يحتوي دليل استكشاف أخطاء العميل 365 على توصيات عالية المستوى لحل المشاكل، وأفضل الممارسات، وروابط لمحتوى استكشاف الأخطاء لكل جزء من دورة تطوير الوكيل 365.

بيانات إمكانية الملاحظة لا تظهر

الأعراض:

العميل يهرب
لا يوجد تتبع في مركز الإدارة
لا يمكن رؤية نشاط العميل

السبب الجذري:

الملاحظة غير مفعلة
أخطاء التكوين
مشاكل حل الرموز

الحلول: جرب الخطوات التالية لحل المشكلة:

التحقق من تمكين مُصدِّر إمكانية المراقبة

يجب تمكين مُصدّر Agent 365 بشكل واضح. عند التعطيل، يعود SDK إلى مُصدّر وحدة التحكم ولا يتم إرسال البيانات الحيوية إلى الخدمة. للحصول على تفاصيل التكوين، راجع التكوين.
التحقق من تكوين محلل الرمز المميز

يتطلب المُصدِّر مُحدِّد رموز صالحًا يُعيد رمز قابلية الملاحظة الخاص بالتطبيق فقط لكل طلب تصدير. إذا كان المحلِّل مفقودًا، أو لم يُعِد رمزًا، أو يطرح استثناءً، فلا يرسل التصدير طلبًا. تأكد من أن كودك ينفذ محلّل التوكن. للحصول على التفاصيل، راجع محلل الرمز المميز.
تحقق من الأخطاء في السجلات

فعّل تسجيل المعلومات بشكل موسع واستخدم الأمر az webapp log tail للبحث في السجلات عن الأخطاء المتعلقة بقابلية المراقبة. للحصول على تفاصيل حول كيفية تمكين التسجيل لكل نظام أساسي، راجع التحقق محليا.
```
# Look for observability-related errors
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```
تحقق من تصدير القياس عن بعد

تأكد من أنه تم توليد القياس عن بعد وتصديره كما هو متوقع.
- أضف مُصدِّر وحدة التحكم وتحقق مما إذا كانت القياسات البُعادية تُنتَج محلياً. للحصول على تفاصيل حول كيفية استخدام مصدر وحدة التحكم والتحقق من صحة الإخراج، راجع التحقق محليا.

معرف المستأجر أو معرف الوكيل مفقود — تم تخطي النطاقات

اعراض: يتجاهل النظام بصمت العمليات ولا يصدرها مطلقًا. تسجل بعض SDKs عدد الامتدادات التي تم تخطيها أو رسالة مثل "لم يتم العثور على أي امتدادات مع هوية المستأجر/العامل." بينما يسقطها الآخرون دون تسجيل الدخول.

القرار:

قبل التصدير، تمتد أقسام SDK حسب هوية المستأجر والعامل. يفلت النظام نطاقات تفتقر إما إلى معرف مستأجر أو معرف عامل ولا ترسلها أبدا إلى الخدمة.
تأكد من إعداد BaggageBuilder مع معرف المستأجر ومعرف الوكيل قبل إنشاء المَتَتالَبات. تنتشر هذه القيم من خلال سياق OpenTelemetry وترتبط بجميع الامتدادات التي تم إنشاؤها ضمن نطاق الحمولة. للحصول على واجهة برمجة التطبيقات الخاصة بالنظام الأساسي، راجع سمات الأمتعة.
تأكد من TurnContext أن النشاط لديه مستلم صالح له هوية الوكيل إذا كنت تستخدم برنامج وسيط الأمتعة أو تحويل مساعد السياق من حزمة تكامل الاستضافة لملء هذه المعرفات.

فشل حل الرمز المميز — تصدير تم تخطيه أو غير مصرح به

الأعراض: يعيد null، أو يعيد مُفسِّر الرمز المميز رمزًا فارغًا، أو يطرح خطأ. يفشل التصدير دون إرسال طلب، ولا يلجأ المُصدِّر إلى المسار المفوض.

القرار:

توفير مُفسِّر يعيد رمز إمكانية الملاحظة النهائي الخاص بالتطبيق فقط لمثيل وكيل التصدير والمستأجر.
تأكد من استخدام معرف المستأجر الصحيح ومعرف العامل ل BaggageBuilder، لأنه يتم تمرير هذه القيم إلى محلل الرمز المميز.
تحقق من سلوك بدء التشغيل الخاص باللغة. يفشل Node.js في التكوين عندما يكون exporter الخاص بـ Agent 365 مفعّلًا بدون resolver، ويفشل .NET في إنشاء الـ exporter، ويعود Python إلى console exporter عندما لا يكون هناك resolver مُكوَّن.
تحقق من أن المُحلِّل يتحقق من صحة الرمز قبل إرجاعه. يجب أن ترفض الرموز المفوضة التي تحمل مطالبة scp والرموز الصادرة للجمهور المستهدف الخطأ.

HTTP 401 غير مصرح به

اعراض: فشل التصدير مع HTTP 401. لا يقوم المصدر بإعادة محاولة هذا الخطأ.

القرار:

تحقق من أن قيمة audience للرمز هي 9b975845-388f-4429-889e-eab1ef63949c أو api://9b975845-388f-4429-889e-eab1ef63949c.
تحقق من أن مُحلِّل الرمز المميز لا يعيد رمز مستخدم مفوض، أو رمزًا يتضمن مطالبة scp، أو رمزًا لجمهور غير صحيح، أو رمزًا مميزًا منتهي الصلاحية.
تأكد من أن المُحلِّل يعيد رمز مثيل الوكيل النهائي، وليس توكيد المخطط الوسيط.

HTTP 403 ممنوع

اعراض: فشل التصدير مع HTTP 403. لا يقوم المصدر بإعادة محاولة هذا الخطأ.

السبب الجذري: يمكن أن يكون لخطأ HTTP 403 أسباب مختلفة. تحقق من الإعدادات التالية بالترتيب.

القرار:

الترخيص مفقود — تأكد من أن المستأجر لديه أحد التراخيص التالية المعينة في مركز إدارة Microsoft 365:
- اختبار - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft وكيل فورنتير 365
مثيل الوكيل غير مسجل — يقبل مسار S2S رمزًا مميزًا خاصًا بالتطبيق فقط من مثيل وكيل مسجل في Agent 365، من دون الدور Agent365.Observability.OtelWrite وإلا، فإنه يعيد HTTP 403 insufficient_scope. بالنسبة لوكلاء المخطط، a365 setup all يسجل مثيل الوكيل. لإعادة محاولة عملية تسجيل فاشلة، شغل a365 setup all --agent-registration-only. إنشاء هوية Microsoft Entra وحده لا يسجل مثيل الوكيل.
الرمز ليس للتطبيق فقط — تحقق من أن الرمز لا يتضمن scp claim. يتطلب مسار S2S رمزًا مميزًا خاصًا بالتطبيق فقط.
الهوية غير المسجلة تفتقر إلى دور التطبيق (App role) — الهويات غير المسجلة، بما في ذلك تسجيلات التطبيقات القياسية التي يستخدمها وكلاء المحرك المخصص، تحتاج إلى Agent365.Observability.OtelWrite دور التطبيق (App role). لمنحه، انظر امنح الإذن.
وكيل SDK 1.x على المسار المفوض — يحتاج المسار المفوض إلى إذن مفوض Agent365.Observability.OtelWrite وموافقة المسؤول، والتي a365 setup all لا تضبط لوكلاء Blueprint. قم بالترقية إلى SDK 2.0، أو امنح الإذن.
معرف الوكيل لا يطابق الرمز — انظر HTTP 403 ممنوع - عدم تطابق معرف الوكيل.

HTTP 403 ممنوع — عدم تطابق معرف الوكيل

الأعراض: يفشل التصدير مع HTTP 403 ورسالة خادم مشابهة لـ 403 Forbidden مع agent-ID-mismatch من حالات الفشل عند استدعاء نقاط نهاية التتبع الخاصة بـ Agent 365.

السبب الجذري: يحدث هذا الخطأ عند استخدام معرف عميل المخطط بدلا من معرف عميل مثيل العامل عند تعيين تفاصيل العامل. لا يتطابق معرف العامل في عنوان URL للتصدير مع الهوية المعتمدة من قبل الرمز المميز، لذلك ترفض نقطة نهاية التتبع الطلب.

القرار:

تحقق مما إذا كان معرف المستأجر قد تمت إضافته إلى قائمة المستأجرين المسموح بها ل Agent 365.
تعيين تفاصيل العامل مع معرف عميل مثيل العامل (وليس معرف عميل المخطط).
تحقق من عنوان URL للتصدير الذي تم إنشاؤه - يتم تسجيله إذا قمت بتمكين المسجل. تأكد من أن معرف العامل في عنوان URL يطابق معرف عميل مثيل العامل.
لتمكين التسجيل التشخيصي لكل SDK، راجع التحقق محليا.

أخطاء HTTP 429 أو 5xx - أخطاء عابرة

اعراض: فشل التصدير مع رمز حالة HTTP عابر مثل 429 أو 5xx.

القرار:

عادة ما تكون هذه الأخطاء عابرة وتحل من تلقاء نفسها. تقوم حزم تطوير البرمجيات Python وJavaScript بإعادة المحاولة تلقائياً عند مواجهة رموز حالة HTTP 408 و429 و5xx حتى ثلاث مرات، باستخدام طريقة التراجع الأسي. لا تتم إعادة محاولة .NET SDK تلقائيا.
إذا استمرت الأخطاء، فتحقق من لوحة معلومات حماية الخدمة.
ضع في اعتبارك تقليل تكرار التصدير عن طريق زيادة التأخير المجدول بين الدفعات أو زيادة الحد الأقصى لحجم دفعة التصدير. للحصول على خيارات التكوين لكل نظام أساسي، راجع الجدول في Agent365ExporterOptionsالتكوين.

مهلة التصدير

الأعراض: انتهت مدة محاولات التصدير.

القرار:

تحقق من اتصال الشبكة بنقطة نهاية إمكانية المراقبة.
تختلف إعدادات المهلة الافتراضية حسب المنصة. مهلة طلب HTTP الافتراضية هي 30 ثانية. تحتوي بعض SDKs أيضا على مهلة مصدرة شاملة منفصلة تغطي دورة التصدير بأكملها بما في ذلك عمليات إعادة المحاولة. للحصول على الخصائص والإعدادات الافتراضية الدقيقة لكل نظام أساسي، راجع Agent365ExporterOptions الجدول في التكوين.
إذا كانت المهلات تحدث بشكل متكرر، فقم بزيادة قيمة المهلة ذات الصلة في خيارات المصدر.

ينجح التصدير ولكن بيانات تتبع الاستخدام لا تظهر في Defender أو Purview

Symptoms: تعرض السجلات تصديرا ناجحا ولكن بيانات تتبع الاستخدام غير مرئية في Microsoft Defender أو Microsoft Purview.

القرار:

تحقق من تلبية المتطلبات الأساسية لعرض السجلات المصدرة. بالنسبة إلى Purview، يجب تشغيل التدقيق. بالنسبة Defender، يجب تكوين التتبع المتقدم. لمزيد من المعلومات، راجع عرض السجلات المصدرة.
يمكن أن يستغرق القياس عن بعد عدة دقائق للتعبئة بعد التصدير الناجح. انتظر حتى تظهر البيانات قبل إجراء مزيد من التحقيق.

لمعرفة المزيد حول اختبار إمكانية المراقبة، راجع:

مفاهيم مراقبة العامل 365 - تدفق البيانات ونماذج الهوية والمصادقة والنطاقات والحدود التي تنطبق على كل مسار تكامل.
مرجع سمة إمكانية ملاحظة العامل 365 - مخطط سمة النطاق المتعارف عليه الذي يجب أن يتوافق مع كل امتداد تم تناوله بواسطة العامل 365.
Microsoft OpenTelemetry Distro - SDK الموحد الموصى به للتكاملات الجديدة.

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-10-02

حزمة SDK للرصد للوكيل 365 المتوقف عن استخدامه

المزايا الرئيسية

الوكلاء المعتمدون

التثبيت

الإعداد

سمات الأمتعة

البرامج الوسيطة للأمتعة

محلل الرمز المميز

التجهيز التلقائي

النواة الدلالية

OpenAI

إطار عمل الوكيل

إطار عمل LangChain

الأدوات اليدوية

استدعاء الوكيل

تنفيذ الأدوات

استدلال

الإخرَاج

التحقق محليا

عرض السجلات المصدرة

التحقق من جاهزية النشر في المتجر

InvokeAgentScope سمات

ExecuteToolScope سمات

InferenceScope سمات

OutputScope سمات

اختبر وكيلك بقدرات المراقبة

استكشاف الأخطاء وإصلاحها

بيانات إمكانية الملاحظة لا تظهر

معرف المستأجر أو معرف الوكيل مفقود — تم تخطي النطاقات

فشل حل الرمز المميز — تصدير تم تخطيه أو غير مصرح به

HTTP 401 غير مصرح به

HTTP 403 ممنوع

HTTP 403 ممنوع — عدم تطابق معرف الوكيل

أخطاء HTTP 429 أو 5xx - أخطاء عابرة

مهلة التصدير

ينجح التصدير ولكن بيانات تتبع الاستخدام لا تظهر في Defender أو Purview

المحتوى ذو الصلة

الملاحظات

الموارد الإضافية

`InvokeAgentScope` سمات

`ExecuteToolScope` سمات

`InferenceScope` سمات

`OutputScope` سمات