SDK של ניראות

חשוב

כדי לאפשר ניראות ב-Agent 365, השתמש ב- Microsoft OpenTelemetry Distro. הפצה זו מספקת SDK אחד של ניראות לצפייה ב-Microsoft, שמספק את Agent 365, Microsoft Foundry, Azure Monitor ועוד. הגישה הקיימת המתוארת במאמר זה ממשיכה לפעול ללא שינויים שיש בהם הפרה של תאימות. להנחיות לגבי העברה לפי שפה, ראה את המדריכים הבאים:

מדריך העברה אל Python
מדריך העברה ל-JavaScript/TypeScript
מדריך העברה ל-.NET עבור מודל הנתונים הבסיסי, זהות ואימות, היקפים והסכמה, ומגבלות - החלים על כל נתיב אינטגרציה - ראה מושגי ניראות של Agent 365.

הערה

ניראות היא אחת מרמות היכולות האינקרמנטליות ב- תחילת העבודה עם Agent 365, והיא חלה על כל סוגי הסוכנים.

כדי להשתתף באקוסיסטמה של Agent 365, הוסף יכולות ניראות של Agent 365 לסוכן שלך. Agent 365 Observability מבוסס על OpenTelemetry ‏(OTel) ומספק מסגרת מאוחדת ללכידת מדידת שימוש באופן עקבי ומאובטח בכל פלטפורמות הסוכנים. על ידי יישום הרכיב הנדרש הזה, אתה מאפשר למנהלי IT לנטר את פעילות הסוכן שלך במרכז הניהול של Microsoft ומאפשר לצוותי אבטחה להשתמש ב-Defender וב-Purview לזיהוי איומים ותאימות.

היתרונות העיקריים

נראות מקצה לקצה: לוכד מדידת שימוש מקיפה עבור כל הפעלה של סוכן, כולל הפעלות, קריאות לכלי וחריגות, ומספק יכולת מעקב מלאה בכל הפלטפורמות.
הפעלת אבטחה תאימות: הזן יומני ביקורת מאוחדים ל-Defender ול-Purview, מה שמאפשר תרחישי אבטחה מתקדמים ודיווחי תאימות לסוכן שלך.
גמישות חוצת פלטפורמות: בנה על תקני OTel ותמוך בזמני ריצה ופלטפורמות מגוונות כמו Copilot Studio, ‏Foundry ומסגרות סוכנים עתידיות.
יעילות תפעולית למנהלים: לספק ניראות מרכזית במרכז הניהול של Microsoft 365, להפחית את זמן פתרון הבעיות ולשפר את הפיקוח עם בקרות גישה מבוססות תפקידים עבור צוותי IT המנהלים את הסוכן.

סוכנים נתמכים

סוגי הסוכנים הבאים תומכים בניראות של Agent 365:

סוכנים שמופעלים ב-Microsoft Agent 365: השתמש ב-SDK של ניראות כדי לכוונן את הסוכן.
סוכני מנוע מותאמים אישית: השתמש ב-SDK של ניראות כדי להכין את הסוכן.
סוכנים הצהרתיים: הניראות נתמכת באופן מובנה. אין צורך ביישום SDK.

התקנה

השתמש בפקודות אלה כדי להתקין את המודולים של ניראות עבור השפות הנתמכות על ידי Agent 365.

התקן את חבילות הליבה של ניראות וזמן ריצה. כל הסוכנים המשתמשים בניראות ב-Agent 365 זקוקים לחבילות אלה.

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

אם הסוכן שלך משתמש בחבילת Microsoft Agents Hosting, התקן את חבילת האינטגרציה של האחסון. הוא מספק תוכנת ביניים שמאכלסת אוטומטית מטען וטווחים מ-TurnContext, וכולל מטמון אסימונים עבור מייצא הניראות.

pip install microsoft-agents-a365-observability-hosting

אם הסוכן שלך משתמש באחת מהמסגרות הנתמכות של בינה מלאכותית, התקן את תוסף התיאום האוטומטי המתאים כדי ללכוד מדידת שימוש אוטומטית ללא קוד תיאום ידני. לפרטים על תצורה, ראה תיאום אוטומטי.

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

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

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

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

התקן את חבילות הליבה של ניראות וזמן ריצה. כל הסוכנים המשתמשים בניראות ב-Agent 365 זקוקים לחבילות אלה.

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

אם הסוכן משתמש בחבילת @microsoft/agents-hosting, התקן את חבילת האינטגרציה של האחסון. הוא מספק תוכנת ביניים שמאכלסת אוטומטית מטען וטווחים מ-TurnContext, וכולל מטמון אסימונים עבור מייצא הניראות.

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

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

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

התקן את חבילת הליבה של ניראות וזמן ריצה. כל הסוכנים המשתמשים בניראות ב-Agent 365 זקוקים לחבילה זו.

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

אם הסוכן משתמש בחבילת Microsoft.Agents.A365.Observability.Hosting NuGet package, התקן את חבילת האינטגרציה של האחסון. היא מספקת תוכנת ביניים שמאכלסת אוטומטית מטען וטווחים מ-TurnContext, וכוללת מטמון אסימונים עבור מייצא הניראות.

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

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

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

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

תצורה

השתמש בהגדרות הבאות כדי להפעיל ולהתאים אישית את Agent 365 Observability עבור הסוכן שלך.

הגדר את משתנה הסביבה ENABLE_A365_OBSERVABILITY_EXPORTER לערך true לצורך ניראות. הגדרה זו מייצאת יומנים לשירות ומחייבת לספק token_resolver. אחרת, נעשה שימוש ביצואן הקונסולה.

from microsoft_agents_a365.observability.core import configure

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

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

פותר האסימונים אינו מנותק מהכניסה לקונסולה.

ניתן להתאים אישית את התנהגות היצואן על ידי העברת מופע של Agent365ExporterOptions אל exporter_options. כאשר exporter_options מסופק, הוא מקבל עדיפות על פני הפרמטרים token_resolver ו-cluster_category.

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

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

הטבלה הבאה מתארת את הפרמטרים האופציונליים עבור configure().

פרמטר	Description	ברירת מחדל
`logger_name`	שם הלוגר של Python המשמש לניפוי שגיאות ופלט יומן קונסולה.	`microsoft_agents_a365.observability.core`
`exporter_options`	`Agent365ExporterOptions` מופע שמגדיר יחד את פותר האסימונים ואת קטגוריית האשכול.	`None`
`suppress_invoke_agent_input`	כאשר `True`, מעכב הודעות קלט על פריסות `InvokeAgent`.	`False`

הטבלה הבאה מתארת את המאפיינים האופציונליים עבור Agent365ExporterOptions.

מאפיין‬	Description	ברירת מחדל
`use_s2s_endpoint`	כַּאֲשֵׁר `True`, משתמש בנתיב נקודת הקצה משירות לשירות.	`False`
`max_queue_size`	גודל תור מקסימלי עבור מעבד האצווה.	`2048`
`scheduled_delay_ms`	עיכוב במילישניות בין אצוות ייצוא.	`5000`
`exporter_timeout_ms`	זמן קצוב במילישניות עבור פעולת הייצוא.	`30000`
`max_export_batch_size`	גודל אצווה מקסימלי עבור פעולות ייצוא.	`512`

הגדר את משתנה הסביבה ENABLE_A365_OBSERVABILITY_EXPORTER לערך true לצורך ניראות. הגדרה זו מייצאת יומנים לשירות ודורשת פותר אסימונים. אחרת, נעשה שימוש ביצואן הקונסולה.

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

// Define a token resolver to authenticate with the observability service for exporting logs
const tokenResolver = (agentId, tenantId) => {
    // Your token resolution logic here
    return "your-token";
};

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

builder.start();

כחלופה למשתני סביבה, ניתן להגדיר ניראות באופן תכנותי באמצעות ספק קונפיגורציה דרך השיטה withConfigurationProvider. אם נעשה שימוש בשיטות builder פרטניות (כגון withExporterOptions או withClusterCategory), שיטות builder פרטניות יקבלו עדיפות על ערכים מספק הקונפיגורציה.

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

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

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

builder.start();

ניתן להתאים אישית את התנהגות היצואן על ידי העברת מופע של Agent365ExporterOptions אל withExporterOptions. כך תוכל לשלוט באצוות, פסקי זמן ומצב הניתוב.

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

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

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

builder.start();

הטבלה הבאה מתארת את המאפיינים האופציונליים עבור Agent365ExporterOptions.

מאפיין‬	Description	ברירת מחדל
`useS2SEndpoint`	כַּאֲשֵׁר `true`, משתמש בנתיב נקודת הקצה משירות לשירות.	`false`
`maxQueueSize`	גודל תור מקסימלי עבור מעבד האצווה.	`2048`
`scheduledDelayMilliseconds`	עיכוב במילישניות בין אצוות ייצוא.	`5000`
`exporterTimeoutMilliseconds`	זמן קצוב במילישניות עבור כל פעולת הייצוא.	`90000`
`httpRequestTimeoutMilliseconds`	זמן קצוב במילישניות עבור כל בקשת HTTP בודדת לשרת האחורי.	`30000`
`maxExportBatchSize`	גודל אצווה מקסימלי עבור פעולות ייצוא.	`512`

ניתן גם לספק לוגר מותאם אישית שמיישם את ממשק ILogger (info, warn, error, event). העבר אותו לבונה באמצעות withCustomLogger.

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

builder.start();

הגדר EnableAgent365Exporter ל- true ב- appsettings.json

ב- Program.cs, הוסף Agent365ExporterOptions לאוסף השירותים. שינוי זה מגדיר את הנציג שמייצא המעקב משתמש בו כדי לאסוף את האסימון.

הוסף יחסי תלות שקשורים לניראות באמצעות AddA365Tracing().

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(sp =>
    {
        return new Agent365ExporterOptions
        {
            TokenResolver = async (agentId, tenantId) =>
            {
                // It's recommended to implement caching in your token provider for performance.
                var token = await tokenProvider.GetObservabilityTokenAsync(agentId, tenantId);
                return token;
            }
        };
    });

builder.AddA365Tracing();

ניתן להתאים אישית את התנהגות היצואן על ידי העברת סוג Configure delegate ו-Exporter ל- AddA365Tracing().

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

הטבלה הבאה מתארת את המאפיינים האופציונליים עבור Agent365ExporterOptions.

מאפיין‬	Description	ברירת מחדל
`UseS2SEndpoint`	כַּאֲשֵׁר `true`, משתמש בנתיב נקודת הקצה משירות לשירות.	`false`
`MaxQueueSize`	גודל תור מקסימלי עבור מעבד האצווה.	`2048`
`ScheduledDelayMilliseconds`	עיכוב במילישניות בין אצוות ייצוא.	`5000`
`ExporterTimeoutMilliseconds`	זמן קצוב במילישניות עבור פעולת הייצוא.	`30000`
`MaxExportBatchSize`	גודל אצווה מקסימלי עבור פעולות ייצוא.	`512`

תכונות תמונה

לְהִשְׁתַמֵשׁ BaggageBuilder כדי להגדיר מידע קונטקסטואלי הזורם דרך כל הטווחים בבקשה. ערכת פיתוח התוכנה (SDK) מיישמת א SpanProcessor שמעתיק את כל רשומות המטען שאינן ריקות לטווחי זמן חדשים שהתחילו מבלי להחליף מאפיינים קיימים.

from microsoft_agents_a365.observability.core import BaggageBuilder

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

כדי לאכלס אוטומטית את BaggageBuilder מתוך TurnContext, השתמש בפונקציית העזר populate שבחבילת microsoft-agents-a365-observability-hosting. עוזר זה מחלץ באופן אוטומטי פרטי מתקשר, סוכן, דייר, ערוץ ושיחה מהפעילות.

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

builder = BaggageBuilder()
populate(builder, turn_context)

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

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

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

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

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

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

כדי לאכלס אוטומטית את BaggageBuilder מתוך TurnContext, השתמש בפונקציית העזר fromTurnContext שבחבילת @microsoft/agents-a365-observability-hosting. עוזר זה מחלץ באופן אוטומטי פרטי מתקשר, סוכן, דייר, ערוץ ושיחה מהפעילות.

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

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

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

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

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

כדי לאכלס אוטומטית את BaggageBuilder מה- ITurnContext, השתמש ב FromTurnContext שיטת ההרחבה ב- Microsoft.Agents.A365.Observability.Hosting חֲבִילָה. שיטה זו מחלצת באופן אוטומטי פרטי מתקשר, סוכן, דייר, ערוץ ושיחה מהפעילות.

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

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

תוכנת ביניים למטען

אם הסוכן שלכם משתמש בחבילת אינטגרציית האירוח, יש לרשום תוכנת ביניים של מזוודות כדי לאכלס אוטומטית את המזוודות עבור כל בקשה נכנסת. שלב זה מבטל את הצורך לקרוא BaggageBuilder ידנית בכל מטפל פעילות.

רשום את BaggageMiddleware בתוכנת הביניים של המתאם. זה מחלץ באופן אוטומטי פרטי מתקשר, סוכן, דייר, ערוץ ושיחה מכל הודעה נכנסת TurnContext ועוטף את הבקשה בטווח מטען.

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

לחלופין, השתמש ב-ObservabilityHostingManager כדי להגדיר תוכנת ביניים של מטען יחד עם תכונות אירוח נוספות:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

התוכנת מתווך מדלגת על הגדרת מטען לתשובות אסינכרוניות (ContinueConversation אירועים) כדי להימנע מחליפת מטען שהבקשה המקורית כבר קבעה.

לִרְשׁוֹם BaggageMiddleware על המתאם . זה מחלץ באופן אוטומטי פרטי מתקשר, סוכן, דייר, ערוץ ושיחה מכל הודעה נכנסת TurnContext ועוטף את הבקשה בטווח מטען.

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

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

לחלופין, השתמש ב-ObservabilityHostingManager כדי להגדיר תוכנת ביניים של מטען יחד עם תכונות אירוח נוספות:

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

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

לִרְשׁוֹם BaggageTurnMiddleware על המתאם. זה מחלץ באופן אוטומטי פרטי מתקשר, סוכן, דייר, ערוץ ושיחה מכל הודעה נכנסת ITurnContext ועוטף את הבקשה בטווח מטען.

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

adapter.Use(new BaggageTurnMiddleware());

אם אתה צריך מטען ברמת HTTP (למשל, כדי להגדיר מזהי דיירים וסוכן לפני שצינור ה-Bot Framework רץ), הירשם ObservabilityBaggageMiddleware בצינור ASP.NET Core באמצעות UseObservabilityRequestContext שיטת ההרחבה. עליך לספק פונקציית פתרון (resolver) אשר מחלצת את מזהה הדייר ומזהה הסוכן מהקשר ה-HTTP.

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

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

פותר אסימונים

כשאתה משתמש ביצוא Agent 365, עליך לספק פונקציה של פתרון אסימון שמחזירה אסימון אימות. כשאתה משתמש ב-SDK של Agent 365 Observability עם מסגרת Agent Hosting, תוכל ליצור אסימונים באמצעות TurnContext מפעילויות סוכן.

המקטע הבא מדגים כיצד ניתן ליצור אסימון באמצעות ממשק ה- SDK של microsoft_agents.hosting.core. אסימון האימות שנוצר כאן משמש לייצוא הטווחים לשירות קליטת הנתונים של A365. סוכנים יכולים ליצור אסימון בעצמם, למשל באמצעות Microsoft Authentication Library ‏(MSAL), אך עליהם לוודא שלאסימון יש את הטווח של ניראות.

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

agents_sdk_config = load_configuration_from_env(environ)

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

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

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

לסוכן שנבנה עם ה-A365 CLI שמשתמש בחבר צוות מבוסס בינה מלאכותית וחבילת Microsoft Agent 365 Observability Hosting Library, השתמש ב- AgenticTokenCache לטיפול אוטומטי במטמון אסימונים. רשום את האסימון פעם אחת לכל סוכן ודייר במהלך הפעלת מטפל, והעבר את cache.get_observability_token בתור token_resolver בתצורת הניראות.

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

# Create a shared cache instance
token_cache = AgenticTokenCache()

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

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

המקטע הבא מדגים כיצד ניתן ליצור אסימון באמצעות ממשק ה- SDK של @microsoft/agents-hosting. אסימון האימות שנוצר כאן משמש לייצוא הטווחים לשירות קליטת הנתונים של A365. סוכנים יכולים ליצור אסימון בעצמם, למשל באמצעות Microsoft Authentication Library ‏(MSAL), אך עליהם לוודא שלאסימון יש את הטווח של ניראות.

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

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

const storage = new MemoryStorage();

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

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

לסוכן שנבנה עם ה-A365 CLI שמשתמש בחבר צוות מבוסס בינה מלאכותית ובחבילה @microsoft/agents-a365-observability-hosting, השתמש ב- AgenticTokenCacheInstance לטיפול אוטומטי במטמון אסימונים. קרא ל-RefreshObservabilityToken פעם אחת לכל סוכן ודייר במהלך מטפל בפעילות, והעבר את AgenticTokenCacheInstance.getObservabilityToken בתור tokenResolver בתצורת הניראות.

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

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

builder.start();

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

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

המקטע הבא מדגים כיצד ניתן ליצור אסימון באמצעות ממשק ה- SDK של אירוח Microsoft.Agents. השתמש באסימון האימות שיצרת כדי לייצא את הטווחים לשירות הקליטה של A365. סוכנים יכולים ליצור אסימון בעצמם, למשל באמצעות Microsoft Authentication Library ‏(MSAL), אך עליהם לוודא שלאסימון יש את הטווח של ניראות.

ספק פותר אסימונים על ידי רישום של Agent365ExporterOptions בנציג TokenResolver. הנציג מקבל את agentId ואת tenantId ומחזיר אסימון אימות.

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

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

עבור סוכן שנבנה עם CLI A365 שמשתמש בחבר צוות מבוסס בינה מלאכותית וחבילת Microsoft.Agents.A365.Observability.Hosting NuGet – השתמש בשיטה AddAgenticTracingExporter() לטיפול אוטומטי במטמון אסימונים באמצעות הזרקת יחסי תלות.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

באפליקציית הסוכן, רשום את האסימון.

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

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

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

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

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

תיאום אוטומטי

התיאום האוטומטי מקשיב אוטומטית למסגרות אג'נטיות (SDK) של אותות מדידת שימוש קיימים עבור עקבות ומעבירה אותם לשירות הניראות של Agent 365. תכונה זו מבטלת את הצורך של מפתחים לכתוב קוד ניטור ידנית, מפשטת את ההגדרה ומבטיחה מעקב ביצועים עקבי.

חשוב

המכשירים האוטומטיים מאכלסים רק את תכונות ה-OTel הסטנדרטיות. עליך להוסיף מאפיינים ספציפיים ל-Microsoft דרך BaggageBuilder. כדי לראות אילו תכונות חסרות, יש לאמת את פלט ה-SPAN של הקונסולה מול יומני האחסון של קבוצת הדיפרנציאלים.

מספר SDK ופלטפורמות תומכים בתיאום אוטומטי:

פלטפורמה	SDK נתמכים / מסגרות
.NET	Semantic Kernel, OpenAI, Agent Framework
Python	Semantic Kernel, OpenAI, Agent Framework, LangChain
Node.js	OpenAI, LangChain

הערה

התמיכה בתיאום אוטומטי משתנה בהתאם לפלטפורמה וליישום SDK.

Semantic Kernel

מדידה אוטומטית דורשת שימוש בבונה מטענים. הגדר מזהה סוכן ומזהה דייר באמצעות BaggageBuilder.

התקנת החבילה.

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

הגדר ניראות.

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

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

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

# Your Semantic Kernel code is now automatically traced

הוסף יחסי תלות לאוסף השירותים.

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

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

הגדר את AgentId ואת TenantId באמצעות BaggageBuilder. ודא שהמזהה שבו אתה משתמש בעת יצירת ChatCompletionAgent תואם למזהה הסוכן שאתה מעביר ל-BaggageBuilder.

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

OpenAI

מדידה אוטומטית דורשת שימוש בבונה מטענים. הגדר מזהה סוכן ומזהה דייר באמצעות BaggageBuilder.

התקנת החבילה.

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

הגדר ניראות.

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

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

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

# Your OpenAI Agents code is now automatically traced

התקנת החבילה.

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

הגדר ניראות.

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

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

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

sdk.start();

instrumentor.enable();

הוסף יחסי תלות לאוסף השירותים.

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

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

הגדר את AgentId ואת TenantId באמצעות BaggageBuilder. לקריאות לכלים, התחל לגלות את המקור על ידי שימוש ב-Trace() במופע ChatToolCall.

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

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

Agent Framework

מדידה אוטומטית דורשת שימוש בבונה מטענים. הגדר מזהה סוכן ומזהה דייר באמצעות BaggageBuilder.

התקנת החבילה.

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

הגדר ניראות.

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

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

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

הוסף יחסי תלות לאוסף השירותים.

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

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

הגדר את AgentId ואת TenantId באמצעות BaggageBuilder.

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

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

LangChain Framework

מדידה אוטומטית דורשת שימוש בבונה מטענים. הגדר מזהה סוכן ומזהה דייר באמצעות BaggageBuilder.

התקנת החבילה.

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

הגדר ניראות.

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

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

# Enable auto-instrumentation
CustomLangChainInstrumentor()

# Your LangChain code is now automatically traced

התקנת החבילה.

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

הגדר ניראות.

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

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

sdk.start();

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

// Your LangChain code is now automatically traced

תיאום ידנית

השתמש ב-Agent 365 observability SDK כדי להבין את הפעולה הפנימית של הסוכן. ה-SDK מספק טווחים שאפשר להתחיל: InvokeAgentScope, ExecuteToolScope, InferenceScope ו- OutputScope.

הפעלת סוכן

השתמש בהיקף זה בתחילת תהליך הסוכן. באמצעות טווח קריאת הסוכן, תוכל ללכוד מאפיינים כמו הסוכן הנוכחי שנקרא, נתוני משתמש של הסוכן, ועוד.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

אם הסוכן שלך משתמש בחבילה @microsoft/agents-a365-observability-hosting, תוכל להשתמש ב-ScopeUtils.populateInvokeAgentScopeFromTurnContext כדי ליצור את הטווח עם פרטי הסוכן, פרטי המתקשר ומידע הערוץ שמופקים אוטומטית מ-TurnContext.

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

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

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

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

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

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

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

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

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

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

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

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

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

        return new AgentResponse { Content = output };
    }
}

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

הרצת כלי

הדוגמאות הבאות מראות כיצד להוסיף מעקב תצפית להרצת הכלי של הסוכן שלך. מעקב זה לוכד מדידת שימוש למטרות ניטור וביקורת.

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

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

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

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

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

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

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

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

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

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

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

אם הסוכן שלך משתמש בחבילת @microsoft/agents-a365-observability-hosting, השתמש ב-ScopeUtils.populateExecuteToolScopeFromTurnContext כדי ליצור את ההיקף עם פרטי הסוכן שמופקים אוטומטית מ-TurnContext.

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

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

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

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

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

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

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

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

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

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

הסקה

הדוגמאות הבאות ממחישות כיצד לבצע תיאום לקריאות הסקה למודלים של AI באמצעות מעקב ניראות, כדי ללכוד שימוש באסימונים, פרטי מודל ומטה-נתונים של תגובה.

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

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

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

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

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

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

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

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

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

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

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

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

אם הסוכן שלך משתמש בחבילת @microsoft/agents-a365-observability-hosting, תוכל להשתמש ב-ScopeUtils.populateInferenceScopeFromTurnContext כדי ליצור את ההיקף עם פרטי הסוכן שמופקים אוטומטית מ-TurnContext.

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

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

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

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

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

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

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

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

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

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

פלט

השתמש בטווח הזה לתרחישים אסינכרוניים שבהם InvokeAgentScope, ExecuteToolScope, או InferenceScope לא יכולים ללכוד נתוני פלט באופן סינכרוני. התחל OutputScope כ-child span כדי להקליט את הודעות הפלט הסופיות לאחר סיום ה-Parent Scope.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

אימות מקומי

כדי לוודא ששילבת בהצלחה את ה-SDK של ניראות, בדקו את יומני הקונסולה שנוצרו על ידי הסוכן ואת הלוגים מ-SDK של ניראות.

הגדר את משתנה סביבה ENABLE_A365_OBSERVABILITY_EXPORTER שיהיה false. ההגדרה הזו מייצאת טווחים (מעקבים) לקונסולה.

כדי לחקור כישלונות ייצוא, הפעל רישום מפורט על ידי הגדרת ENABLE_A365_OBSERVABILITY_EXPORTER ל-true והגדר רישום דיבוג בתחילת הפעלת האפליקציה שלך:

import logging

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

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

הודעות יומן עיקריות:

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

הגדר את משתנה סביבה ENABLE_A365_OBSERVABILITY_EXPORTER שיהיה false. ההגדרה הזו מייצאת טווחים (מעקבים) לקונסולה.

כדי לחקור כישלונות ייצוא, הגדר משתני סביבה בתוך .env או shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

סקור את פלט הקונסולה עבור הודעות כמו:

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

באופן אופציונלי, להשתמש בלוגר מותאם אישית כדי ללכוד אירועי ייצוא לקובץ:

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

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

הגדר EnableAgent365Exporter ל- false ב- appsettings.json ההגדרה הזו מייצאת טווחים (מעקבים) לקונסולה.

כדי לחקור כשלים ביצוא, הגדר רישום מפורט ב-appsettings.json:

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

או הגדר משתני סביבה:

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

הודעות יומן עיקריות:

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

הערה

אם לא רשמת ILoggerFactory ב-DI, המייצא חוזר אוטומטית ליומן קונסולה.

צפייה ביומנים מיוצאים

כדי להציג טלמטריה של סוכן ב-Microsoft Purview או ב-Microsoft Defender, ודא שהדרישות הבאות מתקיימות:

Microsoft Purview: יש להפעיל ביקורת עבור הארגון שלך. להוראות, ראה הפעלה או כיבוי של ביקורת.
Microsoft Defender: יש להגדיר ציד מתקדם כדי לגשת לשולחן CloudAppEvents . למידע נוסף, ראו טבלת CloudAppEvents בסכימת הציד המתקדמת.

אימות לפרסום בחנות

חשוב

כדי שהאימות יתבצע בהצלחה, הסוכן צריך ליישם את הטווחים InvokeAgentScope, InferenceScope ו-ExecuteToolScope. שלושת הטווחים הללו נדרשים לפרסום.

לפני הפרסום, השתמש ביומני הקונסולה כדי לאמת את שילוב הניראות עבור הסוכן על ידי יישום הטווחים הנדרשים invoke agent, execute tool, inference ו-output. לאחר מכן השווה את יומני הסוכן שלך לרשימות התכונות הבאות כדי לוודא שכל התכונות הנדרשות קיימות. לכוד תכונות בכל טווח או דרך בונה המטענים, וכלול תכונות אופציונליות לפי שיקול דעתך.

למידע נוסף על דרישות פרסום בחנות, ראה הנחיות לאימות חנות.

`InvokeAgentScope` תכונות

הרשימה הבאה מסכמת את תכונות מדידת השימוש הנדרשות והאופציונליות שנרשמות עם תחילת InvokeAgentScope.

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

`ExecuteToolScope` תכונות

הרשימה הבאה מסכמת את תכונות מדידת השימוש הנדרשות והאופציונליות שנרשמות עם תחילת ExecuteToolScope.

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

`InferenceScope` תכונות

הרשימה הבאה מסכמת את תכונות מדידת השימוש הנדרשות והאופציונליות שנרשמות עם תחילת InferenceScope.

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

`OutputScope` תכונות

הרשימה הבאה מסכמת את תכונות מדידת השימוש הנדרשות והאופציונליות שנרשמות עם תחילת OutputScope. השתמש בטווח זה לתרחישים אסינכרוניים שבהם טווח האב אינו יכול ללכוד נתוני פלט באופן סינכרוני.

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

בדוק את הסוכן שלך עם יכולת צפייה

לאחר שיישמת ניראות בסוכן שלך, בדוק אותו כדי לוודא שהוא לוכד מדידת שימוש בצורה נכונה. פעל בהתאם ל- testing guide על מנת להגדיר את הסביבה שלך. לאחר מכן, התמקד בעיקר במקטע הצג יומני ניראות כדי לאמת שהיישום שלך עובד כמצופה.

אימות:

מעבר אל: https://admin.cloud.microsoft/#/agents/all
בחר את הסוכן > פעילות
אתה רואה הפעלות וקריאות לכלים

‏‫פתרון בעיות

מקטע זה מתאר בעיות נפוצות בעת יישום ושימוש בניראות.

בעיה	Description
נתוני צפייה אינם מופיעים	אין מדידת שימוש נראית כי הייצוא לא מופעל, הקונפיגורציה שגויה, או שפתרון האסימון נכשל.
חסר מזהה דייר או מזהה סוכן - טווחי זמן שדילגו עליהם	טווחים נפסלים לפני הייצוא כאשר מאפייני הזהות הנדרשים לחלוקה חסרים.
כשל בפתרון אסימון - ייצוא דילג או לא מורשה	בקשות ייצוא נכשלות או מושמטות כאשר הפותר לא מחזיר אסימון או נתקל בחריגה.
HTTP 401 לא מורשה	האימות מצליח מבחינה פורמלית, אך האסימון אינו תקף לקליטה בשל תחום, סוג או תפוגה.
HTTP 403 אסור	הגישה נדחתה עקב פערי רישוי של הלקוח או חוסר בהרשאות ניטור.
HTTP 403 אסור - אי התאמה במזהה הסוכן	הבקשה נדחית כאשר זהות הסוכן בכתובת ה-URL אינה תואמת לזהות שמיוצגת על ידי האסימון.
שגיאות HTTP 429 או 5xx - שגיאות חולפות	הגבלות זמניות או תקלות בצד השירות מפריעות לייצוא ועלולות לדרוש כוונון ניסיונות חוזרים.
פסק זמן לייצוא	אצוות מדידת השימוש עוברות את מגבלת הזמן שהוגדרה עקב השהיית רשת או זמני תגובה איטיים של נקודת הקצה.
הייצוא הצליח אך הטלמטריה לא מופיעה ב-Defender או ב-Purview	הקליטה הושלמה, אך הנראות במורד הזרם מתעכבת או נחסמת בשל דרישות מקדימות של המוצר.

עצה

מדריך פתרון הבעיות של Agent 365 כולל המלצות מתקדמות לפתרון תקלות, שיטות עבודה מומלצות וקישורים לתוכן פתרון תקלות לכל חלק במחזור החיים של פיתוח Agent 365.

נתוני צפייה אינם מופיעים

תסמינים:

הסוכן פועל
אין טלמטריה במרכז הניהול
לא ניתן לראות את פעילות הסוכן

הגורם העיקרי:

ניראות לא מופעלת
טקסט של שגיאת תצורה
בעיות בפתרון אסימונים

פתרונות: נסו את השלבים הבאים כדי לפתור את הבעיה:

וודא שמייצא הניראות מופעל

עליך להפעיל במפורש את ייצואן Agent 365. אם הוא מושבת, ה-SDK חוזר ליצוא קונסולה ומדידת השימוש לא נשלחת לשירות. לפרטי תצורה, ראה תצורה.
בדוק את הגדרות פותר האסימונים

היצואן דורש פתרון אסימון תקף שמחזיר אסימון Bearer עבור כל בקשת ייצוא. אם פותר האסימונים חסר או מחזיר null, הייצוא מדלג בשקט. ודא שהקוד שלך מיישם נכון את פתרון האסימונים. לפרטים, ראה פותר אסימונים.
בדוק שגיאות ביומנים

הפעל רישום מפורט והשתמש בפקודה az webapp log tail לחיפוש ביומנים אחר שגיאות הקשורות לניראות. למידע נוסף על הפעלת רישום לפי פלטפורמה, ראה אימות מקומי.
```
# Look for observability-related errors
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"
```
ודא ייצוא של מדידת שימוש

ודא שמדידת השימוש נוצרת ומיוצאת כמצופה.
- הוסף יצואן קונסולה ובדוק אם מדידת שימוש נוצרת מקומית. לפרטים על שימוש ביצואן למסוף ואימות הפלט, ראה אימות מקומי.

חסר מזהה דייר או מזהה סוכן - טווחי זמן שדילגו עליהם

תסמינים: המערכת משמיטה ספאנים בשקט ואינה מייצאת אותם כלל. חלק מה-SDK מתעדים ספירה של טווחים מדולגים או הודעה כמו "No spans with tenant/agent identity found." אחרים משאירים אותם בלי לרשום.

פתרון:

לפני הייצוא, חלוקות ה-SDK מתפרסות לפי זהות דייר וסוכן. המערכת משחררת טווחים שאין להם מזהה דייר או סוכן ולעולם לא שולחת אותם לשירות.
Ensure BaggageBuilder מוגדרת עם מזהה הדייר ומזהה הסוכן לפני יצירת ה-spans. ערכים אלה מתפשטים דרך ההקשר של OpenTelemetry ומחוברים לכל הטווחים שנוצרו בתוך טווח המטען. ל-API הספציפי לפלטפורמה, ראו מאפייני מטען.
ודא שלפעילות TurnContext יש נמען תקף עם זהות סוכן אם אתה משתמש ב-Baggage Middleware או Turn context helper מחבילת האינטגרציה של האחסון כדי לאכלס את המזהים האלה.

כשל בפתרון אסימון - ייצוא דילג או לא מורשה

תסמינים: פותר האסימונים מחזיר null או זורק שגיאה. בהתאם ל-SDK, מבוצע דילוג על הייצוא או שהבקשה נשלחת ללא כותרת הרשאה ונכשלת עם HTTP 401.

פתרון:

פותר האסימונים נדרש בעת האתחול. אם הוא חסר, הייצואן יציג שגיאה בעת ההפעלה. ודא שסופק פתרון אסימון ומחזיר אסימון Bearer תקף.
ודא שמשתמשים במזהה הדייר ובמזהה הסוכן הנכונים עבור BaggageBuilder, מכיוון שערכים אלה מועברים למנפיק האסימון.
עבור סוכן המתארחים ב-Azure, ודא שהזהות המנוהלת כוללת את הרשאת ה-API הנדרשת עבור טווח התצפית.

HTTP 401 לא מורשה

מאפייני הבעיה: הייצוא נכשל עם HTTP 401. היצואן לא מנסה שוב את השגיאה הזו.

פתרון:

ודא שקהל האסימון תואם להיקף נקודת הקצה של התצפית.
ודא שפותר האסימון אינו מחזיר אסימון משתמש שהוקצה, אסימון עבור קהל שגוי או אסימון שפג תוקפו.

HTTP 403 אסור

מאפייני הבעיה: הייצוא נכשל עם HTTP 403. היצואן לא מנסה שוב את השגיאה הזו.

סיבת שורש: שגיאת HTTP 403 יכולה להיות בעלת סיבות שונות. בדוק את הרזולוציות הבאות לפי הסדר.

פתרון:

רישיון חסר — ודא שלדייר שלך מוקצה אחד מהרישיונות הבאים במרכז הניהול של Microsoft 365:
- בדיקה - Microsoft 365 E7
- Microsoft 365 E7
- Microsoft Agent 365 Frontier
חסרה הרשאה Agent365.Observability.OtelWrite - אם לאחרונה שדרגת את חבילות הניראות שלך, עליך להעניק את ההרשאה הזו. ראה את ההערה החשובה בסעיף הבא.

חשוב

סוכנים קיימים שמשדרגים לגרסאות אלו נדרשים לבצע שלב נוסף

שלב זה חל רק אם אתה משדרג סוכן קיים. התקנת סוכן חדש לא דורשת את השלב הזה. אם אתה משדרג לגרסאות החבילה הבאות או חדשות יותר, עליך להעניק את ההרשאה החדשה Agent365.Observability.OtelWrite לזהות שלך (זהות מנוהלת או הרשמה לאפליקציה). ללא הרשאה זו, ייצוא של מדידת שימוש נכשל עם HTTP 403.

פלטפורמה	גרסה מינימלית שדורשת שלב זה
NET.	`0.3-beta`
Node.js	`0.2.0-preview.1`
Python	`0.3.0`

הענק את ההרשאה על ידי אחת מהאפשרויות הבאות.

אפשרות A ‏– Agent 365 CLI (נדרש חשבון מנהל כללי; יש להריץ מתיקיית פרויקט הסוכן המכילה a365.config.json, או להשתמש ב---agent-name)

a365 setup permissions bot

או, בלי קובץ הגדרות:

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

פקודה זו מעניקה את כל ההרשאות החסרות לבלופרינט, כולל היקפי ניטור.

אפשרות ב' — פורטל Entra (אין צורך בקבצי תצורה; דורשת גישה של מנהל כללי לרישום אפליקציית Blueprint)

עבור אל פורטל אנטר>רישומי אפליקציות> select your Blueprint app.
עבור אל הרשאות API>הוסף הרשאה>ממשקי API בהם הארגון שלי משתמש>חפש את 9b975845-388f-4429-889e-eab1ef63949c.
בחר ב-הרשאות מוסמכות> סמן את Agent365.Observability.OtelWrite>הוסף הרשאות.
חזור על השלבים 2–3, הפעם בחר הרשאות יישום> בדוק את Agent365.Observability.OtelWrite>הוסף הרשאות.
נְקִישָׁה מתן הסכמת מנהל המערכת ולאשר.

גם Agent365.Observability.OtelWrite (מוסמך) וגם Agent365.Observability.OtelWrite (בקשה) מציגים סטטוס Granted.

HTTP 403 אסור - אי התאמה במזהה הסוכן

תסמינים: ייצוא נכשל עם HTTP 403 והודעת שרת דומה לכשלים 403 Forbiddenagent-ID-mismatch שקוראים לסוכן Agent 365 אחרי נקודות קצה.

סיבת שורש: שגיאה זו מתרחשת כאשר משתמשים במזהה לקוח ה-Blueprint במקום במזהה לקוח של מופע הסוכן בעת הגדרת פרטי הסוכן. מזהה הסוכן בכתובת ה-URL של הייצוא אינו תואם לזהות שאושרה על ידי האסימון, ולכן נקודת הקצה של המעקב דוחה את הבקשה.

פתרון:

ודא אם מזהה הדייר נוסף לרשימת הדיירים המורשים ב-Agent 365.
הגדר את פרטי הסוכן עם מזהה לקוח של מופע הסוכן (לא עם מזהה לקוח ה-Blueprint).
אמת את כתובת ה-URL לייצוא שנוצרה - היא נרשמת אם תפעיל את הרישום שלך. ודא שמזהה הסוכן בכתובת ה-URL תואם למזהה הלקוח של מופע הסוכן.
כדי לאפשר רישום אבחון לפי SDK, ראו אימות מקומי.

שגיאות HTTP 429 או 5xx - שגיאות חולפות

תסמינים: הייצוא נכשל עם קוד סטטוס HTTP זמני כמו 429 או 5xx.

פתרון:

שגיאות אלו הן בדרך כלל חולפות ונפתרות מעצמן. ה-SDK של Python ו-JavaScript מנסים אוטומטית מחדש על קודי סטטוס HTTP 408, 429 ו-5xx עד שלוש פעמים עם נסיגה אקספוננציאלית. ה-SDK של ‎.NET לא מנסה שוב אוטומטית.
אם השגיאות נמשכות, בדוק את לוח המחוונים של תקינות השירות.
כדאי להפחית את תדירות הייצוא על ידי הגדלת ההשהיה המתוכננת בין האצוות או הגדלת גודל האצוות המרבי לייצוא. לאפשרויות תצורה לכל פלטפורמה, ראה את הטבלה Agent365ExporterOptions בתצורה של .

פסק זמן לייצוא

תסמינים: ניסיונות הייצוא עוברים זמן.

פתרון:

בדוק את קישוריות הרשת לנקודת הקצה של התצפית.
ערך פסק הזמן המוגדר כברירת מחדל משתנה בין פלטפורמות. ערך ברירת המחדל של בקשת HTTP הוא 30 שניות. חלק מה-SDK כוללים גם פסק זמן נפרד ליצוא הכולל שמכסה את כל מחזור הייצוא כולל ניסיונות חוזרים. לגבי התכונות המדויקות וברירת המחדל לכל פלטפורמה, ראה את הטבלה Agent365ExporterOptions בתצורה של .
אם פסקי הזמן מתרחשים לעיתים קרובות, מומלץ להגדיל את ערך פסק הזמן הרלוונטי בהגדרות היצוא.

הייצוא הצליח אך הטלמטריה לא מופיעה ב-Defender או ב-Purview

תסמינים: יומנים מראים ייצוא מוצלח אך מדידת השימוש אינה נראית ב-Microsoft Defender או Microsoft Purview.

פתרון:

ודא שאתה עומד בדרישות המוקדמות לצפייה ביומנים מיוצאים. עבור Purview, יש להפעיל ביקורת. ב-Defender, עליך להגדיר ציד מתקדם. למידע נוסף, ראה צפייה ביומנים המיוצאים.
אכלוס הטלמטריה יכול להימשך מספר דקות לאחר ייצוא מוצלח. המתן עד שהנתונים יופיעו לפני שתמשיך בבדיקה.

למידע נוסף על בדיקת ניראות, ראה:

מושגי תצפית של Agent 365 - זרימת נתונים, מודלים של זהות, אימות, היקפים ומגבלות החלים על כל נתיב אינטגרציה.
התייחסות למאפיין תצפית של Agent 365 - סכמת תכונות טווח קנונית שכל טווח שנבלע על ידי Agent 365 חייב להתאים אליה.
Microsoft OpenTelemetry Distro - ה-SDK המומלץ לאינטגרציות חדשות.

משוב

האם עמוד זה היה מועיל?

Last updated on 2026-08-05

SDK של ניראות

היתרונות העיקריים

סוכנים נתמכים

התקנה

תצורה

תכונות תמונה

תוכנת ביניים למטען

פותר אסימונים

תיאום אוטומטי

Semantic Kernel

OpenAI

Agent Framework

LangChain Framework

תיאום ידנית

הפעלת סוכן

הרצת כלי

הסקה

פלט

אימות מקומי

צפייה ביומנים מיוצאים

אימות לפרסום בחנות

InvokeAgentScope תכונות

ExecuteToolScope תכונות

InferenceScope תכונות

OutputScope תכונות

בדוק את הסוכן שלך עם יכולת צפייה

‏‫פתרון בעיות

נתוני צפייה אינם מופיעים

חסר מזהה דייר או מזהה סוכן - טווחי זמן שדילגו עליהם

כשל בפתרון אסימון - ייצוא דילג או לא מורשה

HTTP 401 לא מורשה

HTTP 403 אסור

HTTP 403 אסור - אי התאמה במזהה הסוכן

שגיאות HTTP 429 או 5xx - שגיאות חולפות

פסק זמן לייצוא

הייצוא הצליח אך הטלמטריה לא מופיעה ב-Defender או ב-Purview

תוכן קשור

משוב

משאבים נוספים

`InvokeAgentScope` תכונות

`ExecuteToolScope` תכונות

`InferenceScope` תכונות

`OutputScope` תכונות