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

مهم

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

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

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

الرؤية الشاملة: التقاط بيانات تتبع الاِسْتِخْدَام الشاملة لكل استدعاء عامل، بما في ذلك الجلسات واستدعاءات الأَدَوَات والاستثناءات، ما يمنحك إمكانية التتبع الكاملة عبر الأنظمة الأساسية.
تمكين & توافق الامان:قم بإدخال سجلات التدقيق الموحدة في Defender وPurview، مما يتيح سيناريوهات أمان متقدمة وإعداد تقارير الامتثال لوكيلك.
المرونة عبر الأنظمة الأساسية: البناء على معايير OTel ودعم أوقات التشغيل والأنظمة الأساسية المتنوعة مثل Copilot Studio وS 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 والأنظمة الأساسية:

النظام الأساسي	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 واِسْتِخْدَام TenantIdBaggageBuilder. تأكد من أن المعرف المستخدم عند إنشاء يطابق 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 واِسْتِخْدَام TenantIdBaggageBuilder. بالنسبة إلى استدعاءات الأَدَوَات، ابدأ التتبع باِسْتِخْدَام 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 واِسْتِخْدَام TenantIdBaggageBuilder.

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 لقابلية مراقبة Agent 365 لفهم العمل الداخلي للعامل. توفر مجموعة أدوات تطوير البرامج (SDK) ثلاثة نطاقات يمكن البدء فيها: 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; }
}

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

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

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

للتحقق من التنفيذ، اتبع التعليمات للتحقق محليا لإنشاء سجلات وحدة التحكم الخاصة بجهازك. ثم راجع قسم [التحقق من السمات المطلوبة](#validate-for-rewuireds) لتحديد أي السمات مطلوبة وأيها اختيارية. يجب تعيين جميع السمات المطلوبة لتجتاز التحقق بنجاح.

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

قد يتم تعيين الخصائص باستخدام فئة 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"
    }

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

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

الملاحظات

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

Last updated on 2026-01-09

مشاركة عبر

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

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

التثبيت

التكوين

سمات الأمتعة

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

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

نواة دلالية

OpenAI

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

إطار عمل LangChain

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

استدعاء العامل

تنفيذ الأداة

استدلال

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

سجلات عينات

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

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

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

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

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

خصائص InvokeAgentScope

سمات ExecuteToolScope

سمات InferenceScope

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

الملاحظات

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