Observability SDK

مهم

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

إشعار

المراقبة هي واحدة من مستويات القدرات التدريجية في الشروع في تطوير Agent 365 وتنطبق على جميع أنواع العاملين.

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

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

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

العاملون المدعومون

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

التثبيت

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

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

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

إذا كان عاملك يستخدم حزمة استضافة عاملي Microsoft، قم بتثبيت حزمة تكامل الاستضافة. يوفر البرنامج الوسيط الذي يملأ الأمتعة والنطاقات تلقائيًا من 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 لعاملك.

قم بضبط متغير البيئة 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

سمات الأمتعة

يستخدم 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

وسيط الحمولة

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

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

عند اِسْتِخْدَام مصدر Agent 365، يجب توفير دالة محلل الرمز المميز التي ترجع رمز المصادقة المميز. عند اِسْتِخْدَام Agent 365 Observability SDK مع إطار عمل Agent Hosting، يمكنك إنشاء رموز مميزة باِسْتِخْدَام TurnContext أنشطة العامل من

توضح القصاصة البرمجية التالية كيفية إنشاء رمز مميز باستخدام واجهة microsoft_agents.hosting.core : يستخدم الْرمز الْمميز للمصادقة الْذي تم إنشاؤه هنا لتصدير الْامتدادات إلى خدمة استيعاب 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(),
    )

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

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

مهم

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

SDK وأنظمة اساسية متعددة لدعم التجهيز التلقائي:

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

إشعار

يختلف دعم الأجهزة التلقائية حسب النظام الأساسي وتنفيذ 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

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

Agent Framework

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

إطار عمل 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

التدخل اليدوي

يمكن اِسْتِخْدَام SDK لقابلية مراقبة Agent 365 لفهم العمل الداخلي للعامل. توفر حزمة SDK نطاقات يمكنك تفعيلها: InvokeAgentScope, ExecuteToolScope, InferenceScope، و 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(...)

تنفيذ الأداة

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

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)

استدلال

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

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)

الإخرَاج

استخدم هذا النطاق للسيناريوهات غير المتزامنة حيث لا يمكن لـ InvokeAgentScope أو ExecuteToolScope أو 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

التحقق من الصحة محليا

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

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

وللتحقيق في حالات فشل التصدير، قم بتمكين التسجيل المطول عن طريق إعداد 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.

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

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

التحقق من الصلاحية للنشر في Store

مهم

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

قبل النشر، استخدم سجلات وحدة التحكم للتحقق من تكامل الرصد لعامل من خلال تنفيذ النطاقات المطلوبة invoke agent، execute tool، inference، و 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"
    }

اختبار عاملك مع إمكانية المراقبة

بعد تنفيذ إمكانية المُلَاحَظَة في وكيلك، اختبر للتأكد من التقاط بيانات تتبع الاِسْتِخْدَام بشكل صحيح. اتبع دليل الاختبار لإعداد بيئتك. ثم، ركز بشكل أساسي على قسم عرض سجلات إمكانية المراقبة للتحقق من أن تنفيذ إمكانية المراقبة يعمل كما هو متوقع.

التحقق:

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

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

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

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

تلميح

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

بيانات قابلية المراقبة لا تظهر

العلامات:

  • عامل يعمل
  • لا توجد بيانات القياس عن بعد في مركز المسؤولين
  • لا يمكن رؤية نشاط عامل

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

  • لم يتم تمكين المراقبة
  • أخطاء التكوين
  • مشكلات محلل الرموز المميزة

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

  • تحقق من أن مُصدِّر الملاحظة مفعل

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

  • تحقق من تكوين محلل الرموز المميزة

    يتطلب المُصدّر محلل رموز صالحًا يعيد رمز مميز حامل لكل طلب تصدير. إذا كان محلل الرموز المميزة مفقودًا أو أعاد 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"

  • تحقق من قياس تتبع الاستخدام

    تأكد من أن بيانات التليمترية يتم إنشاؤها وتصديرها كما هو متوقع.

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

معرف المستأجر أو معرف العامل مفقودان - تم تخطي بعض التتبعات

الأعراض: النظام يسقط القطع الصامتة ولا يصدرها أبدًا. بعض حزم البرمجيات تسجل عدد الفترات التي تم تخطيها أو رسالة مثل "لم يتم العثور على فترات بهوية المستأجر/عامل"، بينما تقوم أخرى بإسقاطها دون تسجيل أي شيء.

الحل:

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

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

الأعراض: تُرجع وحدة تحليل الرموز null أو تُصدر خطأ. حسب SDK المستخدم، إما يتم تخطي التصدير بالكامل أو يُرسل الطلب بدون رأس المصادقة ويفشل مع HTTP 401.

الحل:

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

HTTP 401 غير مخوّل

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

الحل:

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

HTTP 403 محظور

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

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

الحل:

  • رخصة مفقودة — تحقق من أن المستأجر لديك لديه أحد التراخيص التالية المعينة في مركز مسؤولي Microsoft 365:

    • اختبار - Microsoft 365 E7
    • Microsoft 365 E7
    • Microsoft Agent 365 Frontier

  • الإذن المفقود Agent365.Observability.OtelWrite — إذا قمت مؤخرًا بترقية حزم الرصد، يجب أن تمنح هذا الإذن. انظر الملاحظة المهمة في القسم التالي.

مهم

العاملون الحاليون الذين يرقون إلى إصدارات الحزم هذه يحتاجون إلى خطوة إضافية

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

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

اختر أحد الخيارات التالية لمنح الأذونات.

الخيار أ — أداة Agent 365 لسطر الأوامر (يتطلب حساب مسؤول عام؛ شغّل الأداة من دليل مشروع الوكيل الذي يحتوي على a365.config.json، أو استخدم --agent-name)

a365 setup permissions bot

أو، بدون ملف التكوين:

a365 setup permissions bot --agent-name "<agent-name>"

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

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

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

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

HTTP 403 محظور - عدم تطابق هوية العامل

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

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

الحل:

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

أخطاء HTTP 429 أو 5xx - أخطاء مؤقتة

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

الحل:

  • عادةً ما تكون هذه الأخطاء مؤقتة وتحل من تلقاء نفسها. تُعيد حِزمتا تطوير البرمجيات (SDK) للغتي Python وJavaScript المحاولة تلقائيًا عند تلقي رموز حالة HTTP‏ 408 و429 و5xx، وذلك بحد أقصى ثلاث مرات، مع استخدام التراجع الأُسّي. حزمة تطوير .NET لا تعيد المحاولة تلقائيا.
  • إذا استمرت الأخطاء، تحقق من لوحة تحكم صحة الخدمة.
  • قم بتقليل تكرار التصدير عن طريق زيادة التأخير المجدول بين دفعات التصدير أو زيادة الحد الأقصى لحجم دفعة التصدير. لخيارات التكوين لكل منصة، راجع الجدول Agent365ExporterOptions في قسم التكوين.

مهلة التصدير

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

الحل:

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

نجح التصدير لكن التليمترية لا تظهر في Defender أو Purview

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

الحل:

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

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

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

  • Last updated on