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

مهم

يجب أن تكون جزءًا من برنامج الإصدار الأولي Frontier للحصول على وصول مبكر إلى Microsoft Agent 365. يربطك Frontier مباشرةً بأحدث ابتكارات الذكاء الاصطناعي في Microsoft. تخضع الإصدارات الأولية في Frontier لشروط الإصدار الأولي الحالية لاتفاقيات العملاء. نظرًا لأن هذه الميزات لا تزال قيد التطوير، فقد يتغير توفرها وقدراتها بمرور الوقت.

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

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

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

التثبيت

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

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

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

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

التكوين

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

اضبط متغيرات البيئة للقابلية للملاحظة:

متغير البيئة	الوصف
`ENABLE_OBSERVABILITY=true`	قم بالعلم لتفعيل أو تعطيل التتبع. القيمة الافتراضية هي `false`.
`ENABLE_A365_OBSERVABILITY_EXPORTER=true`	ضبطها لتصدير `true` السجلات إلى الخدمة. وإلا، يتم استخدام مصدر الكونسول.

from microsoft_agents_a365.observability.core import config

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

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

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

اضبط متغيرات البيئة للقابلية للملاحظة:

متغير البيئة	الوصف
`ENABLE_OBSERVABILITY=true`	قم بالعلم لتفعيل أو تعطيل التتبع. القيمة الافتراضية هي `false`.
`ENABLE_A365_OBSERVABILITY_EXPORTER=true`	ضبطها لتصدير `true` السجلات إلى الخدمة. وإلا، يتم استخدام مصدر الكونسول.

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

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();

عين EnableAgent365Exporter الى true in appsettings.json.

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

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

using Microsoft.Agents.A365.Observability.Runtime;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            ClusterCategory = "prod",
            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();

سمات الأمتعة

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

from microsoft_agents_a365.observability.core.middleware.baggage_builder import BaggageBuilder

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

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

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

// Execute operations within the baggage context
baggageScope.run(() => {
  // All spans created within this context will inherit the baggage values
  
  // Invoke another agent
  using agentScope = InvokeAgentScope.start(invokeDetails, agentDetails, tenantDetails);
  // ... agent logic
  
  // Execute tools
  using toolScope = ExecuteToolScope.start(toolDetails, agentDetails, tenantDetails);
  // ... tool logic
});

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

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

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

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.environment_utils 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

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

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

const downloader = new AttachmentDownloader();

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
  };

أضف محلل الرمز المميز العامل إلى مجموعة الخدمة الخاصة بك.

using Microsoft.Agents.A365.Observability;

builder.Services.AddAgenticTracingExporter();

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

using Microsoft.Agents.Builder;
using Microsoft.Agents.Core.Models;
using Microsoft.Extensions.Logging;
using Microsoft.Agents.A365.Observability.Caching;
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
                },
                EnvironmentUtils.GetObservabilityAuthenticationScope()
            );
        }
        catch (Exception ex)
        {
            _logger.LogWarning($"Error registering for observability: {ex.Message}");
        }
    }
}

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

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

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

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

إشعار

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

نواة دلالية

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

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

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

تكوين إمكانية المراقبة.

from microsoft_agents_a365.observability.core.config import configure
from microsoft_agents_a365.observability.extensions.semantic_kernel 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.Services.AddTracing(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.config import configure
from microsoft_agents_a365.observability.extensions.openai_agents 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')
    .withConsoleExporter(true)
);

// 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.Services.AddTracing(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.config import configure
from microsoft_agents_a365.observability.extensions.agentframework.trace_instrumentor import (
    AgentFrameworkInstrumentor,
)

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

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

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

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

builder.Services.AddTracing(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

تقرير عن حالة النظام اليدوي

استخدم SDK لملاحظة العامل 365 لفهم العمل الداخلي للوكيل. توفر مجموعة تطوير البرمجيات ثلاث نطاقات يمكنك البدء بها: InvokeAgentScope، ExecuteToolScope، و InferenceScope.

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

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

from microsoft_agents_a365.observability.core.invoke_agent_scope import InvokeAgentScope
from microsoft_agents_a365.observability.core.invoke_agent_details import InvokeAgentDetails
from microsoft_agents_a365.observability.core.tenant_details import TenantDetails
from microsoft_agents_a365.observability.core.request import Request

invoke_details = InvokeAgentDetails(
    details=agent_details,        # AgentDetails instance
    endpoint=my_endpoint,         # Optional endpoint (with hostname/port)
    session_id="session-42"
)
tenant_details = TenantDetails(tenant_id="tenant-123")
req = Request(content="User asks a question")

with InvokeAgentScope.start(invoke_details, tenant_details, req):
    # Perform agent invocation logic
    response = call_agent(...)

import { 
  InvokeAgentScope, 
  ExecutionType, 
  CallerDetails, 
  EnhancedAgentDetails 
} from '@microsoft/agents-a365-observability';

// Basic agent invocation details
const invokeDetails = {
  agentId: 'email-agent-123',
  agentName: 'Email Assistant',
  ...
  }
};

const tenantDetails = {
  tenantId: 'tenant-789'
};

// Optional: Caller details (human user)
const callerDetails: CallerDetails = {};

// Optional: Caller agent details (for agent-to-agent calls)
const callerAgentDetails: EnhancedAgentDetails = {};

// Enhanced invocation with caller context
using scope = InvokeAgentScope.start(
  invokeDetails,
  tenantDetails,
  callerAgentDetails,
  callerDetails
);

try {
  // Record input messages
  scope.recordInputMessages(['Please help me organize my emails', 'Focus on urgent items']);
  
  // Your agent invocation logic here
  const response = await invokeAgent(invokeDetails.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;
}
// Scope automatically disposed at end of using block

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: Guid.NewGuid().ToString(),
            agentName: "MyAgent",
            agentDescription: "Handles user requests.",
            tenantId: "tenant-789"
        );

        var tenantDetails = new TenantDetails(Guid.Parse("11111111-2222-3333-4444-555555555555"));

        var request = new Request(
            content: userInput,
            executionType: ExecutionType.HumanToAgent,
            sessionId: "session-abc",
            channelMetadata: new ChannelMetadata("webchat", "https://webchat.contoso.com")
        );

        var callerDetails = new CallerDetails(
            callerId: "user-123",
            callerName: "Jane Doe",
            callerUpn: "jane.doe@contoso.com",
            callerUserId: "user-uuid-456",
            tenantId: "tenant-789"
        );

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

        var invokeAgentDetails = new InvokeAgentDetails(endpoint, agentDetails, sessionId: "session-abc");

        var conversationId = "conv-xyz";

        // Start the scope
        using var scope = InvokeAgentScope.Start(
            invokeAgentDetails: invokeAgentDetails,
            tenantDetails: tenantDetails,
            request: request,
            callerAgentDetails: null,
            callerDetails: callerDetails,
            conversationId: conversationId
        );

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

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

        // Simulate agent processing and output
        var output = $"Processed: {userInput}";
        scope.RecordOutputMessages(new[] { output });

        // Optionally record a single response
        scope.RecordResponse(output);

        return new AgentResponse { Content = output };
    }
}

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

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

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

from microsoft_agents_a365.observability.core.execute_tool_scope import ExecuteToolScope
from microsoft_agents_a365.observability.core.tool_call_details import ToolCallDetails

tool_details = ToolCallDetails(
    tool_name="summarize",
    tool_type="function",
    tool_call_id="tc-001",
    arguments="{'text': '...'}",
    description="Summarize provided text",
    endpoint=None  # or endpoint object with hostname/port
)

with ExecuteToolScope.start(tool_details, agent_details, tenant_details):
    result = run_tool(tool_details)

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

const toolDetails = {
  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'
  }
};

using scope = ExecuteToolScope.start(toolDetails, agentDetails, tenantDetails);

try {
  // Execute the tool
  const result = await searchEmails(toolDetails.arguments);
  
  // Record the tool execution result
  scope.recordResponse(JSON.stringify(result));
  
  return result;
} catch (error) {
  scope.recordError(error as Error);
  throw error;
}

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

public class MyToolAgent
{
    public async Task<ToolResult> ExecuteTool(string toolName, object parameters)
    {
        var agentDetails = new AgentDetails(
            agentId: Guid.NewGuid().ToString(),
            agentName: "ToolAgent",
            agentDescription: "Executes tools for users.",
            agentAUID: "tool-auid-123",
            agentUPN: "toolagent@contoso.com",
            agentBlueprintId: "tool-blueprint-456",
            agentType: AgentType.EntraEmbodied,
            tenantId: "tenant-789"
        );

        var tenantDetails = new TenantDetails(Guid.Parse("11111111-2222-3333-4444-555555555555"));

        var endpoint = new Uri("https://toolagent.contoso.com:8443");

        var toolCallDetails = new ToolCallDetails(
            toolName: toolName,
            arguments: System.Text.Json.JsonSerializer.Serialize(parameters),
            toolCallId: Guid.NewGuid().ToString(),
            description: "Runs a tool operation.",
            toolType: "custom-type",
            endpoint: endpoint
        );

        // Start the scope
        using var scope = ExecuteToolScope.Start(
            toolCallDetails: toolCallDetails,
            agentDetails: agentDetails,
            tenantDetails: tenantDetails
        );

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

        // Record response
        var toolOutput = $"Tool '{toolName}' processed with parameters: {System.Text.Json.JsonSerializer.Serialize(parameters)}";
        scope.RecordResponse(toolOutput);

        return new ToolResult { Output = toolOutput };
    }
}

public class ToolResult
{
    public string Output { get; set; }
}

استدلال

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

from microsoft_agents_a365.observability.core.inference_scope import InferenceScope
from microsoft_agents_a365.observability.core.inference_call_details import InferenceCallDetails
from microsoft_agents_a365.observability.core.request import Request

inference_details = InferenceCallDetails(
    operationName=SomeEnumOrValue("chat"),
    model="gpt-4o-mini",
    providerName="azure-openai",
    inputTokens=123,
    outputTokens=456,
    finishReasons=["stop"],
    responseId="resp-987"
)
req = Request(content="Explain quantum computing simply.")

with InferenceScope.start(inference_details, agent_details, tenant_details, req):
    completion = call_llm(...)

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

const inferenceDetails = {
  operationName: InferenceOperationType.CHAT,
  model: 'gpt-4',
  providerName: 'openai',
  inputTokens: 150,
  outputTokens: 75,
  finishReasons: ['stop'],
  responseId: 'resp-123456'
};

using scope = InferenceScope.start(inferenceDetails, agentDetails, tenantDetails);

try {
  // 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);  // Update if different from constructor
  scope.recordOutputTokens(82);  // Update if different from constructor
  scope.recordResponseId('resp-789123');
  scope.recordFinishReasons(['stop', 'max_tokens']);
  
  return response.text;
} catch (error) {
  scope.recordError(error as Error);
  throw error;
}

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

public class MyInferenceAgent
{
    public async Task<InferenceResult> RunInference(string input)
    {
        var agentDetails = new AgentDetails(
            agentId: Guid.NewGuid().ToString(),
            agentName: "InferenceAgent",
            agentDescription: "Performs generative AI inference.",
            agentAUID: "inference-auid-123",
            agentUPN: "inferenceagent@contoso.com",
            agentBlueprintId: "inference-blueprint-456",
            agentType: AgentType.EntraEmbodied,
            tenantId: "tenant-789"
        );

        var tenantDetails = new TenantDetails(Guid.Parse("11111111-2222-3333-4444-555555555555"));

        var inferenceDetails = new InferenceCallDetails(
            operationName: InferenceOperationType.Chat,
            model: "gpt-4",
            providerName: "OpenAI",
            inputTokens: 42,
            outputTokens: 84,
            finishReasons: new[] { "stop", "length" },
            responseId: "response-xyz"
        );

        // Start the scope
        using var scope = InferenceScope.Start(
            details: inferenceDetails,
            agentDetails: agentDetails,
            tenantDetails: tenantDetails
        );

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

        // Record input/output messages and other telemetry
        scope.RecordInputMessages(new[] { input, "additional context" });
        scope.RecordOutputMessages(new[] { "AI response message" });
        scope.RecordInputTokens(42);
        scope.RecordOutputTokens(84);
        scope.RecordResponseId("response-xyz");
        scope.RecordFinishReasons(new[] { "stop", "length" });
        scope.RecordThoughtProcess("Reasoning step 1; step 2");

        return new InferenceResult { Output = "AI response message" };
    }
}

public class InferenceResult
{
    public string Output { get; set; }
}

التحقق محليا

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

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

سجلات عينات

قد تبدو السجلات مختلفة قليلا حسب المنصة.

سجل وحدة التحكم Invoke agent span

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

    {
    "name": "invoke_agent Azure OpenAI Agent",
    "context": {
        "trace_id": "0x4bd8f606688c3f3347d69c1b6539c957",
        "span_id": "0x0766d68605234692",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2025-11-24T16:16:54.017403Z",
    "end_time": "2025-11-24T16:17:09.373357Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "operation.source": "SDK",
        "correlation.id": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "gen_ai.conversation.item.link": "http://localhost:56150/_connector",
        "gen_ai.agent.upn": "Delivery Agent",
        "gen_ai.agent.user.id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
        "gen_ai.caller.id": "bbbbbbbb-cccc-dddd-2222-333333333333",
        "gen_ai.caller.name": "Alex Wilber",
        "gen_ai.caller.upn": "Sample UPN",
        "gen_ai.channel.name": "msteams",
        "gen_ai.system": "az.ai.agent365",
        "gen_ai.operation.name": "invoke_agent",
        "gen_ai.agent.id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "gen_ai.agent.applicationid": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "gen_ai.conversation.id": "__PERSONAL_CHAT_ID__",
        "tenant.id": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "session.id": "__PERSONAL_CHAT_ID__",
        "gen_ai.execution.type": "HumanToAgent",
        "gen_ai.input.messages": "[\"hi, what can you do\"]",
        "gen_ai.output.messages": "[\"Hi! I can assist you with a variety of tasks, including answering questions, providing information on a wide range of topics, helping with problem-solving, offering writing assistance, and more. Just let me know what you need help with!\"]"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "MyAgentTesting",
            "service.name": "MyAgentTracing"
        },
        "schema_url": ""
    }}

سجل الكونسول لأداة التنفيذ

يظهر هذا المثال مدى أداة التنفيذ النموذجي الذي يصدره مصدر وحدة التحكم أثناء التحقق المحلي.

{
    "name": "execute_tool get_weather",
    "context": {
        "trace_id": "0xa9a1be6323bd52476d6a28b8893c6aa8",
        "span_id": "0x1dec90d34ecc0823",
        "trace_state": "[]"
    },
    "kind": "SpanKind.INTERNAL",
    "parent_id": "0x2e727b4c133cbd50",
    "start_time": "2025-11-24T18:47:55.960305Z",
    "end_time": "2025-11-24T18:47:55.962306Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "operation.source": "SDK",
        "correlation.id": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "gen_ai.conversation.item.link": "http://localhost:56150/_connector",
        "gen_ai.agent.upn": "Delivery Agent",
        "gen_ai.agent.user.id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
        "gen_ai.execution.type": "HumanToAgent",
        "gen_ai.channel.name": "msteams",
        "gen_ai.system": "az.ai.agent365",
        "gen_ai.operation.name": "execute_tool",
        "gen_ai.agent.id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "gen_ai.agent.applicationid": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "gen_ai.conversation.id": "__PERSONAL_CHAT_ID__",
        "tenant.id": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "gen_ai.tool.name": "get_weather",
        "gen_ai.tool.arguments": "current location",
        "gen_ai.tool.type": "function",
        "gen_ai.tool.call.id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
        "gen_ai.tool.description": "Executing get_weather tool"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "MyAgentTesting",
            "service.name": "MyAgentTracing"
        },
        "schema_url": ""
    }
}

مدى استنتاج سجل وحدة التحكم

يظهر هذا المثال فترة استنتاج نموذجية يخرجه مصدري وحدة التحكم للتحقق المحلي.

{
    "name": "Chat gpt-4o-mini",
    "context": {
        "trace_id": "0xceb86559a6f7c2c16a45ec6e0b201ae1",
        "span_id": "0x475beec8c1c4fa56",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": "0x959a854f18fa2c22",
    "start_time": "2025-11-24T18:04:07.061703Z",
    "end_time": "2025-11-24T18:04:09.506951Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "operation.source": "SDK",
        "correlation.id": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "gen_ai.conversation.item.link": "http://localhost:56150/_connector",
        "gen_ai.agent.upn": "Delivery Agent",
        "gen_ai.agent.user.id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
        "gen_ai.execution.type": "HumanToAgent",
        "gen_ai.channel.name": "msteams",
        "gen_ai.system": "az.ai.agent365",
        "gen_ai.agent.id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "gen_ai.agent.name": "Azure OpenAI Agent",
        "gen_ai.agent.description": "An AI agent powered by Azure OpenAI",
        "gen_ai.agent.applicationid": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "gen_ai.conversation.id": "__PERSONAL_CHAT_ID__",
        "tenant.id": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "gen_ai.input.messages": "hi, what can you do",
        "gen_ai.operation.name": "Chat",
        "gen_ai.request.model": "gpt-4o-mini",
        "gen_ai.provider.name": "Azure OpenAI",
        "gen_ai.output.messages": "\"Hello! I can help answer questions, provide information, assist with problem-solving, offer writing suggestions, and more. Just let me know what you need!\"",
        "gen_ai.usage.input_tokens": "33",
        "gen_ai.usage.output_tokens": "32",
        "gen_ai.response.finish_reasons": "[\"stop\"]"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.38.0",
            "service.namespace": "MyAgentTesting",
            "service.name": "MyAgentTracing"
        },
        "schema_url": ""
    }
}

متطلبات الملاحظة

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

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

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

راجع الخصائص المطلوبة وقيم المعلمات الموصوفة لهذه الفئات:

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

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

البيانات	الوصف
`invoke_agent_details.details.agent_id`	المعرف الفريد لعامل الذكاء الاصطناعي
`invoke_agent_details.details.agent_name`	اسم عامل الذكاء الاصطناعي القابل للقراءة من قبل الإنسان
`invoke_agent_details.details.agent_auid`	معرف مستخدم العامل (AUID)
`invoke_agent_details.details.agent_upn`	اسم المستخدم الأساسي للعامل (UPN)
`invoke_agent_details.details.agent_blueprint_id`	معرف مخطط/تطبيق العامل
`invoke_agent_details.details.tenant_id`	معرف المستأجر للعامل
`invoke_agent_details.details.conversation_id`	معرف المحادثة أو الجلسة
`invoke_agent_details.endpoint`	نقطة النهاية لادعاء العامل
`tenant_details.tenant_id`	المعرف الفريد للمستأجر
`request.content`	محتوى الحمولة المرسلة إلى الوكيل لاستدعائه
`request.execution_type`	نوع الاستدعاء الذي يشير إلى أصل الطلب (على سبيل المثال، `HumanToAgent` أو `AgentToAgent`)
`caller_details.caller_id`	المعرف الفريد للمتصل
`caller_details.caller_upn`	اسم المستخدم الأساسي (UPN) للمتصل
`caller_details.caller_user_id`	معرف المستخدم للمتصل
`caller_details.tenant_id`	معرف المستأجر للمتصل

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

البيانات	الوصف
`details.tool_name`	اسم الأداة التي يتم تنفيذها
`details.arguments`	وسائط الأدوات أو المعلمات
`details.tool_call_id`	المعرف الفريد لاستدعاء الأداة
`details.tool_type`	نوع الأداة التي يتم تنفيذها
`details.endpoint`	إذا تم إجراء استدعاء أداة خارجية
`agent_details.agent_id`	المعرف الفريد لعامل الذكاء الاصطناعي
`agent_details.agent_name`	اسم عامل الذكاء الاصطناعي القابل للقراءة من قبل الإنسان
`agent_details.agent_auid`	معرف المستخدم للوكيل
`agent_details.agent_upn`	اسم المستخدم الأساسي للعامل (UPN)
`agent_details.agent_blueprint_id`	مخطط الوكيل أو معرف التطبيق
`agent_details.tenant_id`	معرف المستأجر للوكيل.
`agent_details.conversation_id`	معرف المحادثة الخاص باستدعاء الوكيل.
`tenant_details.tenant_id`	معرف المستأجر للوكيل.

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

البيانات	الوصف
`details.operationName`	اسم العملية أو نوع الاستدلال
`details.model`	اسم النموذج أو المعرف
`details.providerName`	اسم المزود
`agent_details.agent_id`	المعرف الفريد لعامل الذكاء الاصطناعي
`agent_details.agent_name`	اسم عامل الذكاء الاصطناعي القابل للقراءة من قبل الإنسان
`agent_details.agent_auid`	معرف مستخدم العامل (AUID)
`agent_details.agent_upn`	اسم المستخدم الأساسي للعامل (UPN)
`agent_details.agent_blueprint_id`	مخطط الوكيل أو معرف التطبيق
`agent_details.tenant_id`	المعرف الفريد للمستأجر
`agent_details.conversation_id`	معرف المحادثة أو الجلسة
`tenant_details.tenant_id`	المعرف الفريد للمستأجر
`request.content`	يتم إرسال محتوى الحمولة إلى الوكيل للاستنتاج
`request.execution_type`	نوع الاستدعاء الذي يشير إلى أصل الطلب (على سبيل المثال، `HumanToAgent` أو `AgentToAgent`)
`request.source_metadata`	تمثيل معلومات القناة

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

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

البيانات	الوصف
`invokeAgentDetails.agentAUID`	معرف مستخدم العامل (AUID)
`invokeAgentDetails.agentBlueprintId`	معرف مخطط/تطبيق العامل
`invokeAgentDetails.agentId`	المعرف الفريد لعامل الذكاء الاصطناعي
`invokeAgentDetails.agentName`	اسم عامل الذكاء الاصطناعي القابل للقراءة من قبل الإنسان
`invokeAgentDetails.agentUPN`	اسم المستخدم الأساسي للعامل (UPN)
`invokeAgentDetails.conversationId`	معرف المحادثة أو الجلسة
`invokeAgentDetails.endpoint.host`	عنوان المضيف لنقطة النهاية لاستدعاء الوكيل
`invokeAgentDetails.endpoint.port`	رقم المنفذ لنقطة النهاية لاستدعاء الوكيل
`invokeAgentDetails.endpoint.protocol`	نقطة نهاية البروتوكول لاستدعاء الوكيل
`invokeAgentDetails.request.content`	محتوى حمولة الطلب الخاصة باستدعاء الوكيل
`invokeAgentDetails.request.executionType`	نوع استدعاء حمولة الطلب الخاصة باستدعاء الوكيل
`invokeAgentDetails.request.sourceMetadata.name`	معلومات القناة مثل (`msteams`، `email`، وهكذا)
`invokeAgentDetails.tenantId`	معرف المستأجر للعامل
`tenantDetails.tenantId`	المعرف الفريد للمستأجر
`callerDetails.callerId`	المعرف الفريد للمتصل (aadObjectId)
`callerDetails.callerName`	اسم العرض للمتصل
`callerDetails.callerUpn`	اسم المستخدم الأساسي (UPN) للمتصل
`callerDetails.tenantId`	معرف المستأجر للمتصل

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

البيانات	الوصف
`details.arguments`	وسائط الأدوات أو المعلمات
`details.endpoint.host`	عنوان المضيف لنقطة النهاية لتنفيذ الأداة. مطلوب إذا تم إجراء مكالمة خارجية
`details.endpoint.port`	رقم المنفذ لنقطة النهاية لتنفيذ الأداة. مطلوب إذا تم إجراء مكالمة خارجية
`details.endpoint.protocol`	بروتوكول نقطة النهاية لتنفيذ الأداة. مطلوب إذا تم إجراء مكالمة خارجية
`details.toolCallId`	المعرف الفريد لاستدعاء الأداة
`details.toolName`	اسم الأداة التي يتم تنفيذها
`details.toolType`	نوع الأداة التي يتم تنفيذها
`agentDetails.agentId`	المعرف الفريد لعامل الذكاء الاصطناعي
`agentDetails.agentName`	اسم عامل الذكاء الاصطناعي القابل للقراءة من قبل الإنسان
`agentDetails.conversationId`	معرف المحادثة أو الجلسة
`tenantDetails.tenantId`	المعرف الفريد للمستأجر

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

البيانات	الوصف
`details.model`	اسم النموذج أو المعرف
`details.operationName`	اسم العملية أو نوع الاستدلال
`details.providerName`	اسم المزود
`agentDetails.agentId`	المعرف الفريد لعامل الذكاء الاصطناعي
`agentDetails.agentName`	اسم عامل الذكاء الاصطناعي القابل للقراءة من قبل الإنسان
`agentDetails.conversationId`	معرف المحادثة أو الجلسة
`tenantDetails.tenantId`	المعرف الفريد للمستأجر

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

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

البيانات	الوصف
`invokeAgentDetails.details.agentId`	المعرف الفريد للوكيل.
`invokeAgentDetails.details.agentName`	اسم العرض للوكيل.
`invokeAgentDetails.details.agentAUID`	معرف مستخدم Azure (AUID) للوكيل.
`invokeAgentDetails.details.agentUPN`	اسم المستخدم الرئيسي (UPN) للوكيل.
`invokeAgentDetails.details.agentBlueprintId`	المخطط/معرف التطبيق للوكيل.
`invokeAgentDetails.details.tenantId`	معرف المستأجر للوكيل.
`invokeAgentDetails.endpoint`	نقطة النهاية URI للوكيل الذي يجب استدعاؤه.
`tenantDetails.tenantId`	معرف المستأجر.
`request.content`	محتوى الحمولة الذي يتم توفيره للوكيل.
`request.executionType`	نوع التنفيذ الذي يصف الطلب.
`request.sourceMetadata.name`	اسم المصدر قابل للقراءة من قبل الإنسان. اسم القناة.
`conversationId`	معرف المحادثة الخاص باستدعاء الوكيل.

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

البيانات	الوصف
`details.toolName`	اسم الأداة التي يتم استدعاؤها.
`details.arguments`	تم تمرير حجج متسلسلة إلى الأداة.
`details.toolCallId`	معرف استدعاء الأداة.
`details.toolType`	تصنيف النوع للأداة.
`details.endpoint`	نقطة النهاية المطلوبة لتنفيذ الأدوات عن بعد.
`agentDetails.agentId`	المعرف الفريد للوكيل.
`agentDetails.agentName`	اسم العرض للوكيل.
`agentDetails.agentAUID`	معرف مستخدم Azure (AUID) للوكيل.
`agentDetails.agentUPN`	اسم المستخدم الرئيسي (UPN) للوكيل.
`agentDetails.agentBlueprintId`	المخطط/معرف التطبيق للوكيل.
`agentDetails.tenantId`	معرف المستأجر للوكيل.
`tenantDetails.tenantId`	معرف المستأجر.

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

البيانات	الوصف
`details.operationName`	معرف التليمترية لعملية الاستدلال.
`details.model`	اسم النموذج المستخدم لتلبية طلب الاستنتاج.
`details.providerName`	مقدم الخدمة المسؤول عن مكالمة الاستدلال.
`agentDetails.agentId`	المعرف الفريد للوكيل.
`agentDetails.agentName`	اسم العرض للوكيل.
`agentDetails.agentAUID`	معرف مستخدم Azure (AUID) للوكيل.
`agentDetails.agentUPN`	اسم المستخدم الرئيسي (UPN) للوكيل.
`agentDetails.agentBlueprintId`	المخطط/معرف التطبيق للوكيل.
`agentDetails.tenantId`	معرف المستأجر للوكيل.
`tenantDetails.tenantId`	معرف المستأجر.
`parentId`	للإدارة الصريحة لنطاق الوالد. هذا غير مطلوب في معظم الحالات.

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

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

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

خصائص InvokeAgentScope

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

"attributes": {
        "correlation.id": "Optional",
        "gen_ai.agent.applicationid": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "gen_ai.agent.platformid": "Optional",
        "gen_ai.agent.type": "Optional",
        "gen_ai.agent.thought.process": "Optional",
        "gen_ai.agent.upn": "Required",
        "gen_ai.agent.user.id": "Required",
        "gen_ai.caller.agent.applicationid": "Required (if execution type is agent to agent)",
        "gen_ai.caller.agent.id": "Required (if execution type is agent to agent)",
        "gen_ai.caller.agent.name": "Required (if execution type is agent to agent)",
        "gen_ai.caller.agent.platformid": "Optional",
        "gen_ai.caller.agent.type": "Optional",
        "gen_ai.caller.client.ip": "Required",
        "gen_ai.caller.id": "Required",
        "gen_ai.caller.name": "Optional",
        "gen_ai.caller.upn": "Required",
        "gen_ai.channel.link": "Optional",
        "gen_ai.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "gen_ai.conversation.item.link": "Optional",
        "gen_ai.execution.type": "Required",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Required (Set by the SDK)",
        "gen_ai.output.messages": "Required",
        "gen_ai.system": "Optional",
        "hiring.manager.id": "Optional",
        "operation.source": "Required (SDK sets a default value)",
        "server.address": "Required",
        "server.port": "Required",
        "session.id": "Optional",
        "session.description": "Optional",
        "tenant.id": "Required"
    },

سمات ExecuteToolScope

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

"attributes": {
        "correlation.id": "Optional",
        "gen_ai.agent.applicationid": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "gen_ai.agent.platformid": "Optional",
        "gen_ai.agent.type": "Optional",
        "gen_ai.agent.upn": "Required",
        "gen_ai.agent.user.id": "Required",
        "gen_ai.caller.client.ip": "Required",
        "gen_ai.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "gen_ai.conversation.item.link": "Optional",
        "gen_ai.execution.type": "Optional",
        "gen_ai.operation.name": "Required (Set by the SDK)",
        "gen_ai.system": "Optional",
        "gen_ai.tool.arguments": "Required",
        "gen_ai.tool.call.id": "Required",
        "gen_ai.tool.description": "Optional",
        "gen_ai.tool.name": "Required",
        "gen_ai.tool.type": "Required",
        "hiring.manager.id": "Optional",        
        "operation.source": "Required (SDK sets a default value)",
        "server.address": "Required (if tool call is external)",
        "server.port": "Required (if tool call is external)",
        "session.id": "Optional",
        "session.description": "Optional",
        "tenant.id": "Required"
    },

سمات InferenceScope

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

"attributes": {
        "correlation.id": "Optional",
        "gen_ai.agent.applicationid": "Required",
        "gen_ai.agent.description": "Optional",
        "gen_ai.agent.id": "Required",
        "gen_ai.agent.name": "Required",
        "gen_ai.agent.platformid": "Optional",
        "gen_ai.agent.type": "Optional",
        "gen_ai.agent.thought.process": "Optional",
        "gen_ai.agent.upn": "Required",
        "gen_ai.agent.user.id": "Required",
        "gen_ai.caller.client.ip": "Required",
        "gen_ai.channel.link": "Optional",
        "gen_ai.channel.name": "Required",
        "gen_ai.conversation.id": "Required",
        "gen_ai.conversation.item.link": "Optional",
        "gen_ai.execution.type": "Optional",
        "gen_ai.input.messages": "Required",
        "gen_ai.operation.name": "Chat",
        "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",
        "hiring.manager.id": "Optional",
        "operation.source": "Required (SDK sets a default value)",
        "session.description": "Optional",
        "session.id": "Optional",
        "tenant.id": "Required"
    }

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

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

التحقق:

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

Troubleshooting

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

Tip

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

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

الأعراض:

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

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

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

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

تحقق من إمكانية الملاحظة مفعلة

فعل علامات الملاحظة في بيئتك.
```
# .env file
ENABLE_OBSERVABILITY=true
ENABLE_A365_OBSERVABILITY_EXPORTER=true
```
Check token resolver configuration

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

استخدم الأمر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"
```
تحقق من تصدير القياس عن بعد

تأكد من أن القياس عن بعد تم توليدها وتصديرها كما هو متوقع.
- إضافة مصدر للكونسول للاختبار
- تحقق مما إذا كان التليمترية مولدة محليا

تعرف أكثر على اختبار قابلية الملاحظة:

الملاحظات

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

Last updated on 2026-02-19

مشاركة عبر

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

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

التثبيت

التكوين

سمات الأمتعة

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

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

نواة دلالية

OpenAI

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

إطار عمل LangChain

تقرير عن حالة النظام اليدوي

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

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

استدلال

التحقق محليا

سجلات عينات

سجل وحدة التحكم Invoke agent span

سجل الكونسول لأداة التنفيذ

مدى استنتاج سجل وحدة التحكم

متطلبات الملاحظة

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

خصائص InvokeAgentScope

سمات ExecuteToolScope

سمات InferenceScope

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

Troubleshooting

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

الملاحظات

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