قابلية الرصد للعوامل

Important

لتمكين إمكانية المراقبة في Agent 365، استخدم Microsoft OpenTelemetry Distro. يوفر هذا التوزيع SDK قابلية المراقبة الفردية عبر Microsoft، مما يساهم في تفعيل Agent 365، وMicrosoft Foundry، وAzure Monitor، والمزيد. يستمر النهج الحالي الموضح في هذه المقالة في العمل دون كسر التغييرات. سيوفر Microsoft أيضا إرشادات الترحيل لمنح العملاء وقتا وافرا للانتقال.

ملاحظة

تعتبر إمكانية الرصد واحدة من مستويات القدرة المتزايدة في بدء استخدام تطوير 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 لتحقيق الملاحظة. يقوم هذا الإعداد بتصدير السجلات إلى الخدمة ويتطلب أن يتم توفير token_resolver. وإلا، يتم استخدام مُصدِّر وحدة التحكم.

from microsoft_agents_a365.observability.core import configure

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Implement secure token retrieval here
    return "Bearer <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().

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

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

الخاصية	الوصف	افتراضي
`use_s2s_endpoint`	عندما `True`، يتم استخدام مسار نقطة النهاية بين الخدمات.	`False`
`max_queue_size`	الحد الأقصى لحجم قائمة الانتظار لمعالج الدفعات.	`2048`
`scheduled_delay_ms`	التأخير بالمللي ثانية بين دفعات التصدير.	`5000`
`exporter_timeout_ms`	المهلة بالمللي ثانية لعملية التصدير.	`30000`
`max_export_batch_size`	الحد الأقصى لحجم الدفعة لعمليات التصدير.	`512`

قم بتعيين متغير البيئة ENABLE_A365_OBSERVABILITY_EXPORTER إلى true لتحقيق الملاحظة. يقوم هذا الإعداد بتصدير السجلات إلى الخدمة ويتطلب توفير محلل رمز مميز. وإلا، يتم استخدام مُصدِّر وحدة التحكم.

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

// Define a token resolver to authenticate with the observability service for exporting logs
const tokenResolver = (agentId, tenantId) => {
    // Your 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.

الخاصية	الوصف	افتراضي
`useS2SEndpoint`	عندما `true`، يتم استخدام مسار نقطة النهاية بين الخدمات.	`false`
`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.

في 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) =>
            {
                // It's recommended to implement caching in your token provider for performance.
                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.

الخاصية	الوصف	افتراضي
`UseS2SEndpoint`	عندما `true`، يتم استخدام مسار نقطة النهاية بين الخدمات.	`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 Observability SDK مع إطار عمل Agent Hosting، يمكنك إنشاء رموز مميزة باستخدام TurnContext من أنشطة العامل.

توضح القصاصة البرمجية التالية كيفية إنشاء رمز مميز باستخدام microsoft_agents.hosting.core SDK. يُستخدم رمز المصادقة الذي تم إنشاؤه هنا لتصدير المسارات إلى خدمة استيعاب A365. يمكن للوكلاء إنشاء رمز مميز بأنفسهم، على سبيل المثال باستخدام مكتبة مصادقة Microsoft (MSAL)، لكنهم بحاجة إلى التأكد من أن الرمز المميز له نطاق المراقبة.

from microsoft_agents.activity import load_configuration_from_env
from microsoft_agents.authentication.msal import MsalConnectionManager
from microsoft_agents.hosting.aiohttp import CloudAdapter
from microsoft_agents.hosting.core import (
    AgentApplication,
    Authorization,
    MemoryStorage,
    TurnContext,
    TurnState,
)
from microsoft_agents_a365.runtime import (
    get_observability_authentication_scope,
)

agents_sdk_config = load_configuration_from_env(environ)

STORAGE = MemoryStorage()
CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
ADAPTER.use(TranscriptLoggerMiddleware(ConsoleTranscriptLogger()))
AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)

AGENT_APP = AgentApplication[TurnState](
    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    aau_auth_token = await AGENT_APP.auth.exchange_token(
                        context,
                        scopes=get_observability_authentication_scope(),
                        auth_handler_id="AGENTIC",
                    )
    # cache this auth token and return via token resolver

بالنسبة إلى عامل تم إنشاؤه باستخدام A365 CLI الذي يستخدم زميلا في فريق الذكاء الاصطناعي وحزمة مكتبة استضافة إمكانية مراقبة Microsoft Agent 365 ، استخدم AgenticTokenCache للتعامل مع التخزين المؤقت للرمز المميز تلقائيا. سجل الرمز المميز مرة واحدة لكل وكيل ومستأجر أثناء معالج النشاط، ومرر cache.get_observability_token كـ token_resolver في تكوين إمكانية المراقبة.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import (
    AgenticTokenCache,
    AgenticTokenStruct,
)
from microsoft_agents_a365.runtime import get_observability_authentication_scope

# Create a shared cache instance
token_cache = AgenticTokenCache()

# Use the cache as your token resolver in configure()
configure(
    service_name="my-agent-service",
    service_namespace="my.namespace",
    token_resolver=token_cache.get_observability_token,
)

@AGENT_APP.activity("message", auth_handlers=["AGENTIC"])
async def on_message(context: TurnContext, _state: TurnState):
    token_cache.register_observability(
        agent_id="agent-456",
        tenant_id="tenant-123",
        token_generator=AgenticTokenStruct(
            authorization=AGENT_APP.auth,
            turn_context=context,
        ),
        observability_scopes=get_observability_authentication_scope(),
    )

توضح القصاصة البرمجية التالية كيفية إنشاء رمز مميز باستخدام @microsoft/agents-hosting SDK. يُستخدم رمز المصادقة الذي تم إنشاؤه هنا لتصدير المسارات إلى خدمة استيعاب A365. يمكن للوكلاء إنشاء رمز مميز بأنفسهم، على سبيل المثال باستخدام مكتبة مصادقة Microsoft (MSAL)، لكنهم بحاجة إلى التأكد من أن الرمز المميز له نطاق المراقبة.

import {
  TurnState,
  AgentApplication,
  MemoryStorage,
  TurnContext,
} from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';
import { getObservabilityAuthenticationScope } from '@microsoft/agents-a365-runtime';

interface ConversationState {
  count: number;
}
type ApplicationTurnState = TurnState<ConversationState>;

const storage = new MemoryStorage();

export const agentApplication = new AgentApplication<ApplicationTurnState>({
  authorization: {
    agentic: {}, // We have the type and scopes set in the .env file
  },
  storage,
});

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const aauAuthToken = await agentApplication.authorization.exchangeToken(context, 'agentic', {
      scopes: getObservabilityAuthenticationScope()
    });
    // cache this auth token and return via token resolver
  }
);

بالنسبة إلى عامل تم إنشاؤه باستخدام A365 CLI الذي يستخدم زميلا في فريق الذكاء الاصطناعي والحزمة @microsoft/agents-a365-observability-hosting ، استخدم AgenticTokenCacheInstance للتعامل مع التخزين المؤقت للرمز المميز تلقائيا. اتصل بـ RefreshObservabilityToken مرة واحدة لكل وكيل ومستأجر أثناء معالج النشاط، و قم بتمرير AgenticTokenCacheInstance.getObservabilityToken باعتباره tokenResolver في تكوين إمكانية المراقبة لديك.

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

// Use the cache as your token resolver in configure()
const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver((agentId, tenantId) =>
      AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId)
    )
);

builder.start();

agentApplication.onActivity(
  ActivityTypes.Message,
  async (context: TurnContext, state: ApplicationTurnState) => {
    const agentId = context.activity.recipient?.agenticAppId || '';
    const tenantId = context.activity.recipient?.tenantId || '';

    await AgenticTokenCacheInstance.RefreshObservabilityToken(
      agentId,
      tenantId,
      context,
      agentApplication.authorization,
      getObservabilityAuthenticationScope()
    );
  }
);

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

يرجى توفير محلل للرموز عبر تسجيل Agent365ExporterOptions باستخدام TokenResolver مفوض. يتلقى المفوض agentId وtenantId ثم يعيد رمز المصادقة.

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

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // Implement your token retrieval logic here
                return await GetTokenAsync(agentId, tenantId);
            }
        };
    });

بالنسبة إلى عامل تم إنشاؤه باستخدام A365 CLI الذي يستخدم زميلا في فريق الذكاء الاصطناعي وحزمة Microsoft.Agents.A365.Observability.Hosting NuGet، استخدم AddAgenticTracingExporter() الأسلوب للتعامل مع التخزين المؤقت للرمز المميز تلقائيا من خلال حقن التبعية.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

في تطبيق العامل، قم بتسجيل الرمز المميز.

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

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<AgenticTokenStruct> _agentTokenCache;
    private readonly ILogger<MyAgent> _logger;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<AgenticTokenStruct> agentTokenCache, ILogger<MyAgent> logger)
        : base(options)
    {
        _agentTokenCache = agentTokenCache ?? throw new ArgumentNullException(nameof(agentTokenCache));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        using var baggageScope = new BaggageBuilder()
            .TenantId(turnContext.Activity.Recipient.TenantId)
            .AgentId(turnContext.Activity.Recipient.AgenticAppId)
            .Build();

        try
        {
            _agentTokenCache.RegisterObservability(
                turnContext.Activity.Recipient.AgenticAppId,
                turnContext.Activity.Recipient.TenantId,
                new AgenticTokenStruct(
                    userAuthorization: UserAuthorization,
                    turnContext: turnContext,
                    authHandlerName: "AGENTIC"
                ),
                EnvironmentUtils.GetObservabilityAuthenticationScope()
            );
        }
        catch (Exception ex)
        {
            _logger.LogWarning($"Error registering for observability: {ex.Message}");
        }
    }
}

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

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

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

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

ملاحظة

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

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

تتطلب الأجهزة التلقائية اِسْتِخْدَام منشئ الأمتعة. قم بتعيين معرف الوكيل ومعرف المستأجر باستخدام 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

تتطلب الأجهزة التلقائية اِسْتِخْدَام منشئ الأمتعة. قم بتعيين معرف الوكيل ومعرف المستأجر باستخدام 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>);
    }
}

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

تتطلب الأجهزة التلقائية اِسْتِخْدَام منشئ الأمتعة. قم بتعيين معرف الوكيل ومعرف المستأجر باستخدام 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

تتطلب الأجهزة الآلية اِسْتِخْدَام منشئ الأمتعة. قم بتعيين معرف الوكيل ومعرف المستأجر باستخدام 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

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

استخدم حزمة أدوات التفاعل مع العامل 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
اختر نشاط وكيلك >
ترى جلسات العمل ومكالمات الأدوات

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

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

Tip

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

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

الأعراض:

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

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

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

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

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

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

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

فعّل تسجيل المعلومات بشكل موسع واستخدم الأمر 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 أو يسبب خطأً. اعتمادا على SDK، يتم تخطي التصدير بالكامل أو يتم إرسال الطلب دون عنوان تخويل ويفشل مع HTTP 401.

القرار:

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

HTTP 401 غير مصرح به

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

القرار:

تحقق من تطابق جمهور الرمز مع نطاق واجهة المراقبة.
تحقق من أن محلل الرمز المميز لا يرجع رمزا مميزا للمستخدم المفوض أو رمزا مميزا لجمهور غير صحيح أو رمزا مميزا منتهي الصلاحية.

HTTP 403 ممنوع

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

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

القرار:

الترخيص مفقود — تأكد من أن المستأجر لديه أحد التراخيص التالية المعينة في مركز إدارة Microsoft 365:
- Test - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft وكيل فورنتير 365
إذن مفقود Agent365.Observability.OtelWrite — إذا قمت مؤخرا بترقية حزم المراقبة الخاصة بك، فستحتاج إلى منح هذا الإذن. راجع الملاحظة المهمة أدناه.

Important

يتطلب الوكلاء الحاليون الذين يقومون بترقية إصدارات الحزمة هذه خطوة إضافية

تنطبق هذه الخطوة فقط إذا كنت تقوم بترقية عامل موجود. لا تتطلب عمليات تثبيت الوكيل الجديدة هذه الخطوة. إذا كنت تقوم بالترقية إلى إصدارات الحزمة التالية أو الإصدارات الأحدث، فيجب عليك منح الإذن الجديد Agent365.Observability.OtelWrite لهويتك (الهوية المدارة أو تسجيل التطبيق). بدون هذا الإذن، يفشل تصدير التيليمتري مع HTTP 403.

النظام الأساسي	الحد الأدنى للإصدار الذي يتطلب هذه الخطوة
.NET	`0.3-beta`
Node.js	`0.2.0-preview.1`
Python	`0.3.0`

امنح الإذن باستخدام أحد الخيارات التالية.

Option A — Agent 365 CLI (يتطلب a365.config.jsona365.generated.config.json في دليل التكوين، حساب مسؤول عام، Agent 365 CLI v1.1.139-preview أو أحدث)

a365 setup admin --config-dir "<path-to-config-dir>"

يمنح هذا الأمر كافة الأذونات المفقودة، بما في ذلك نطاقات المراقبة الجديدة.

الخيار ب - مدخل إنترا (لا توجد ملفات تكوين مطلوبة؛ يتطلب وصول المسؤول العام إلى تسجيل تطبيق المخطط)

انتقل إلى مدخل Entra>App registrations> حدد تطبيق Blueprint.
انتقل إلى أذونات واجهة برمجة التطبيقات>، ثم انقر على إضافة إذن>، واختر واجهات برمجة التطبيقات التي تستخدمها مؤسستي>، وابحث عن 9b975845-388f-4429-889e-eab1ef63949c.
حدد الأذونات المفوضة> تحقق من Agent365.Observability.OtelWrite>إضافة أذونات.
كرر الخطوة من 2 إلى 3، هذه المرة حدد أذونات> التطبيق حدد Agent365.Observability.OtelWrite> أذونات.
انقر فوق منح موافقة المسؤول والتأكيد.

يجب أن يُظهر كل من Agent365.Observability.OtelWrite (المفوض) و Agent365.Observability.OtelWrite (التطبيق) حالة Granted.

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، يجب تكوين التتبع المتقدم. لمزيد من المعلومات، راجع عرض السجلات المصدرة.
يمكن أن يستغرق القياس عن بعد عدة دقائق للتعبئة بعد التصدير الناجح. انتظر حتى تظهر البيانات قبل إجراء مزيد من التحقيق.

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

الملاحظات

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

Last updated on 2026-05-01

قابلية الرصد للعوامل

الفوائد الرئيسية

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

التثبيت

التكوين

سمات الأمتعة

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

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

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

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

OpenAI

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

إطار عمل LangChain

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

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

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

استدلال

إخراج

التحقق محليا

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

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

InvokeAgentScope سمات

ExecuteToolScope سمات

InferenceScope سمات

OutputScope سمات

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

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

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

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

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

HTTP 401 غير مصرح به

HTTP 403 ممنوع

HTTP 429 / 5xx — أخطاء عابرة

مهلة التصدير

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

الملاحظات

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

`InvokeAgentScope` سمات

`ExecuteToolScope` سمات

`InferenceScope` سمات

`OutputScope` سمات