Наблюдаемость агента

Это важно

Чтобы получить ранний доступ для Майкрософт Агента 365, вам нужно попасть в программу предварительного просмотра Frontier<> Frontier напрямую связывает вас с последними инновациями Майкрософт в области искусственного интеллекта. Предпросмотры Frontier подчиняются существующим условиям предварительного просмотра в рамках ваших клиентских соглашений. Так как эти функции еще находятся в разработке, их доступность и возможности могут со временем меняться.

Чтобы участвовать в экосистеме Agent 365, добавьте возможности наблюдаемости Agent 365 к вашему агенту. Agent 365 Observability основан на OpenTelemetry (OTel ) и предоставляет единую структуру для последовательного и безопасного захвата телеметрии на всех платформах агентов. Реализуя этот необходимый компонент, вы даёте ИТ-администраторам возможность отслеживать активность вашего агента в административном центре Майкрософт и позволяете командам безопасности использовать Defender и Purview для соблюдения требований и обнаружения угроз.

Ключевые преимущества

• Сквозная видимость: Захватывайте подробную телеметрию для каждого вызова агента, включая сессии, вызовы инструментов и исключения, обеспечивая полную отслеживаемость между платформами.
• Security and compliance enablement: Вводите унифицированные журналы аудита в Defender и Purview, позволяя создавать продвинутые сценарии безопасности и отчётность по соблюдению требований для вашего агента.
• Кроссплатформенная гибкость: Строить на стандартах OTel и поддерживать разнообразные runtime и платформы, такие как Copilot Studio, Foundry и фреймворки будущих агентов.
• Операционная эффективность для администраторов: Обеспечьте централизованную наблюдаемость в Центр администрирования Microsoft 365, сокращая время устранения неполадок и улучшая управление с помощью ролевых контролей доступа для ИТ-команд, управляющих вашим агентом.

Installation

Используйте эти команды для установки модулей наблюдаемости для языков, поддерживаемых агентом 365.

Python

Установите пакеты для наблюдения ядра и runtime. Все агенты, использующие Agent 365 Observability, нуждаются в таких пакетах.

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

Если ваш агент использует пакет Майкрософт 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

JavaScript

Установите пакеты для наблюдения ядра и runtime. Все агенты, использующие Agent 365 Observability, нуждаются в таких пакетах.

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

Если ваш агент использует пакет @microsoft/agents-hosting , установите пакет интеграции хостинга. Он предоставляет промежуточное ПО, которое автоматически заполняет багаж и области из TurnContext, а также включает кэш токенов для экспортера наблюдаемости.

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

Если ваш агент использует один из поддерживаемых ИИ-фреймворков, установите соответствующее расширение автоинструментации для автоматического захвата телеметрии без ручного кода инструментатора. Для подробностей конфигурации см. Авто-инструментирование.

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

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

.NET

Установите пакет для наблюдения ядра и времени выполнения. Все агенты, использующие Agent 365 Observability, нуждаются в этом пакете.

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

Если ваш агент использует Майкрософт. 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

Конфигурация

Используйте следующие настройки, чтобы включить и настроить наблюдаемость агента 365 для вашего агента.

Python

Установите 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 параметрами и (and 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

JavaScript

Установите ENABLE_A365_OBSERVABILITY_EXPORTER переменную среды на true для наблюдаемости. Эта настройка экспортирует логи в сервис и требует предоставления резольвера токенов. В противном случае используется консольный экспортер.

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

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

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

builder.start();

В качестве альтернативы переменным среды можно программно настроить наблюдаемость, используя поставщик конфигурации через withConfigurationProvider метод. Если вы также используете индивидуальные методы сборщика (например withExporterOptions , или withClusterCategory), индивидуальные методы конструктора имеют приоритет над значениями поставщика конфигурации.

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

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

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

builder.start();

Вы можете настроить поведение экспортера, передав Agent365ExporterOptions экземпляр в withExporterOptions. Эта опция позволяет управлять пакетированием, тайм-аутом и режимом маршрута.

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

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

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

builder.start();

Следующая таблица описывает необязательные свойства для Agent365ExporterOptions.

Недвижимость	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();

.NET

Установите 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 и тип экспортера в 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 , которая копирует все непустые записи багажа в только что начатые споведы без перезаписи существующих атрибутов.

Python

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

JavaScript

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

.NET

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 в пакете Майкрософт.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 вручную в каждом обработчике активности.

Python

Зарегистрируйтесь 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)

Middleware пропускает настройку багажа для асинхронных ответов (ContinueConversation событий), чтобы избежать перезаписи багажа, который уже задал исходный запрос.

JavaScript

Регистрируйтесь 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 });

Middleware пропускает настройку багажа для асинхронных ответов (ContinueConversation событий), чтобы избежать перезаписи багажа, который уже задал исходный запрос.

.NET

Регистрируйтесь BaggageTurnMiddleware на адаптере. Он автоматически извлекает данные звонящего, агента, арендатора, канала и разговора из каждого ITurnContext входящего и заворачивает запрос в багажную зону.

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

adapter.Use(new BaggageTurnMiddleware());

Middleware пропускает настройку багажа для асинхронных ответов (ContinueConversation событий), чтобы избежать перезаписи багажа, который уже задал исходный запрос.

Если вам нужен багаж уровня HTTP (например, для установки идентификаторов арендаторов и агентов до запуска конвейера Bot Framework), зарегистрируйте ObservabilityBaggageMiddleware в ASP.NET Core конвейере с помощью метода расширения UseObservabilityRequestContext. Необходимо предоставить функцию резолвера, которая извлекает идентификатор арендатора и идентификатор агента из контекста HTTP.

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

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

Token resolver

При использовании экспортера Agent 365 необходимо предоставить функцию резольвера токенов, которая возвращает токен аутентификации. Когда вы используете SDK Agent 365 Observability с фреймворком Agent Hosting, вы можете генерировать токены с помощью TurnContext действий from agent.

Python

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

В случае с цифровым работником, если ваш агент использует пакет Майкрософт 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(),
    )

JavaScript

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

В случае с цифровым работником, если ваш агент использует пакет @microsoft/agents-a365-observability-hosting , AgenticTokenCacheInstance используйте автоматическое кэширование токенов. Звоните RefreshObservabilityToken один раз на агента и арендатора во время обработки активности и используйте AgenticTokenCacheInstance.getObservabilityTokentokenResolver его в конфигурации наблюдаемости.

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

.NET

Предоставьте резолвер токенов, зарегистрировавшись 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);
            }
        };
    });

В случае с цифровым работником, если ваш агент использует Майкрософт. Agents.A365.Observability.Hosting NuGet package, используйте метод 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. Эта функция устраняет необходимость для разработчиков вручную писать мониторинговый код, упрощает настройку и обеспечивает последовательное отслеживание производительности.

Несколько SDK и платформ поддерживают автоинструментирование:

Platform	Поддерживаемые пакеты SDK / Платформы
.NET	Semantic Kernel, OpenAI, Agent Framework
Python	Semantic Kernel, OpenAI, Agent Framework, LangChain
Node.js	OpenAI,LangChain

Замечание

Поддержка автоматического инструментирования зависит от реализации платформы и пакета SDK.

Semantic Kernel

Для автоматического инструментирования требуется использование построителя багажа. Задайте идентификатор агента и идентификатор арендатора с помощью BaggageBuilder.

Python

Установите пакет .

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

JavaScript

Semantic Kernel не поддерживается с JavaScript.

.NET

Добавьте зависимости в коллекцию служб.

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

Открытый ИИ

Для автоматического инструментирования требуется использование построителя багажа. Задайте идентификатор агента и идентификатор арендатора с помощью BaggageBuilder.

Python

Установите пакет .

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

JavaScript

Установите пакет .

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

.NET

Добавьте зависимости в коллекцию служб.

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

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

Установите AgentId и TenantId с помощью BaggageBuilder. Для вызовов инструментов начинайте трассировку, используя Trace() на экземпляре ChatToolCall .

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

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

Платформа агента

Для автоматического инструментирования требуется использование построителя багажа. Задайте идентификатор агента и идентификатор арендатора с помощью BaggageBuilder.

Python

Установите пакет .

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

JavaScript

Платформа агента не поддерживается в JavaScript.

.NET

Добавьте зависимости в коллекцию служб.

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

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

Установите AgentId и TenantId с помощью BaggageBuilder.

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

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

Фреймворк LangChain

Автоматическое инструментирование требует использования построителя багажа. Задайте идентификатор агента и идентификатор арендатора с помощью BaggageBuilder.

Python

Установите пакет .

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

JavaScript

Установите пакет .

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

.NET

LangChain не поддерживается с .NET.

Ручное инструментирование

Используйте SDK наблюдаемости Agent 365, чтобы понять внутреннюю работу агента. SDK предоставляет скопы, которые можно запустить: InvokeAgentScope, ExecuteToolScope, InferenceScope, и OutputScope.

Вызов агента

Используйте этот прицел в начале процесса получения агента. Используя область действия агента вызова, вы можете захватывать такие свойства, как текущий вызываемый агент, данные пользователя агента и другие.

Python

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

JavaScript

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

.NET

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

Запуск инструмента

Следующие примеры показывают, как добавить отслеживание наблюдаемости в работу инструмента вашего агента. Это отслеживание фиксирует телеметрию для мониторинга и аудита.

Python

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)

JavaScript

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

.NET

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.\"}");

Вывод

В следующих примерах показано, как инструментировать вызовы вывода модели ИИ с отслеживанием наблюдаемости для отслеживания использования маркеров, сведений о модели и метаданных ответа.

Python

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)

JavaScript

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

.NET

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 с дочернего span для записи финальных выходных сообщений после завершения родительского диапазона.

Python

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

JavaScript

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

.NET

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 наблюдаемости.

Python

Задайте для переменной ENABLE_A365_OBSERVABILITY_EXPORTER среды значение false. Эта настройка экспортирует spans (traces) в консоль.

Чтобы расследовать сбои при экспорте, включите подробное логирование, установив ENABLE_A365_OBSERVABILITY_EXPORTER и true настроив логирование отладки в запуске приложения:

import logging

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

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

Сообщения в журнале ключей:

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

JavaScript

Задайте для переменной ENABLE_A365_OBSERVABILITY_EXPORTER среды значение false. Эта настройка экспортирует spans (traces) в консоль.

Чтобы расследовать сбои при экспорте, установите переменные среды в .env или shell:

# Enable the Agent365 exporter
ENABLE_A365_OBSERVABILITY_EXPORTER=true

# Enable verbose logging
A365_OBSERVABILITY_LOG_LEVEL=info|warn|error

Проверьте вывод консоли для таких сообщений, как:

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

По желанию используйте пользовательский логгер для захвата событий экспорта в файл:

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

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

.NET

Установите EnableAgent365Exporter в false в appsettings.json. Эта настройка экспортирует spans (traces) в консоль.

Чтобы расследовать сбои при экспорте, настройте подробный вход в appsettings.jsonсистему:

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

Или задайте переменные среды:

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

Сообщения в журнале ключей:

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

Замечание

Если вы не регистрируете ILoggerFactory DI, экспортер автоматически возвращается к консольному логгеру.

Просмотр экспортированных логов

Чтобы просматривать телеметрию агентов в Microsoft Purview или Microsoft Defender, убедитесь, что выполнены следующие требования:

• Microsoft Purview: Аудит должен быть включен для вашей организации. Инструкции см. в разделе Включение и отключение аудита.
• Microsoft Defender: Расширенная охота должна быть настроена для доступа к таблице CloudAppEvents. Для подробностей смотрите таблицу CloudAppEvents в расширенной схеме охоты.

Валидация для публикации в магазине

Перед публикацией используйте консольные логи для проверки интеграции наблюдаемости агента, реализуя необходимые invoke agent, execute tool, inferenceи output область видимости. Затем сравните логи вашего агента со следующими списками атрибутов, чтобы убедиться, что все необходимые атрибуты присутствуют. Фиксируйте атрибуты на каждом прицеле или через конструктор багажа, а также добавляйте дополнительные атрибуты по своему усмотрению.

Для получения дополнительной информации о требованиях к публикации в магазине см. рекомендации по валидации магазинов.

атрибуты InvokeAgentScope

Следующий список обобщает обязательные и необязательные атрибуты телеметрии, зафиксированные при запуске InvokeAgentScope.

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

атрибуты ExecuteToolScope

Следующий список обобщает обязательные и необязательные атрибуты телеметрии, зафиксированные при запуске ExecuteToolScope.

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

атрибуты InferenceScope

Следующий список обобщает обязательные и необязательные атрибуты телеметрии, зафиксированные при запуске InferenceScope.

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

атрибуты OutputScope

Следующий список обобщает обязательные и необязательные атрибуты телеметрии, зафиксированные при запуске OutputScope. Используйте этот диапазон для асинхронных сценариев, когда родительский область не может синхронно захватывать выходные данные.

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

Испытайте своего агента с использованием наблюдаемости

После того как вы реализуете наблюдаемость в вашем агенте, проверьте его, чтобы убедиться, что телеметрия фиксируется правильно. Следуйте руководству по тестированию , чтобы настроить свою среду. Затем сосредоточьтесь преимущественно на разделе журналов наблюдаемости, чтобы проверить, что реализация наблюдаемости работает как ожидается.

Проверка

• Перейдите по адресу https://admin.cloud.microsoft/#/agents/all
• Выберите активность вашего агента >
• Вы видите сессии и наборы инструментов

Troubleshooting

В этом разделе описываются распространённые задачи при реализации и использовании наблюдаемости.

Подсказка

Руководство по устранению неполадок Agent 365 содержит рекомендации по решению неполадок на высоком уровне, лучшие практики и ссылки на контент по устранению неполадок для каждой части жизненного цикла разработки Agent 365.

Данные о наблюдаемости не отображаются

Симптомы

• Агент бежит
• В административном центре нет телеметрии
• Не вижу активности агентов

Первопричина.

• Наблюдаемость не включена
• Ошибки конфигурации
• Проблемы с резолвером токенов

Решения: Попробуйте следующие шаги для решения проблемы:

• Проверьте, что экспортер наблюдаемости включён

  Вы должны явно включить экспортер Agent 365. Когда он отключён, SDK возвращается к консольному экспортеру, и телеметрия не отправляется на сервис. Для подробностей конфигурации см. раздел «Конфигурация».

• Check token resolver configuration

  Экспортер требует действительный резолвер токенов, который возвращает токен Bearer для каждого запроса на экспорт. Если резолвер токенов отсутствует или возвращается null, экспорт тихо пропускается. Убедитесь, что ваш код правильно реализует токен-резолвер. Для подробностей см. раздел Token resolver.

• Проверьте ошибки в логах

  Включите подробный лог и используйте 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"
  

• Проверка экспорта телеметрии

  Убедитесь, что телеметрия генерируется и экспортируется как ожидается.

  • Добавьте консольный экспортер и проверьте, генерируется ли телеметрия локально. Для подробностей о том, как использовать консольный экспортер и проверять вывод, смотрите Validate locally.

Отсутствующий идентификатор арендатора или идентификатор агента — пропущены периоды

Симптомы: Система бесшумно сбрасывает развязки и никогда их не экспортирует. Некоторые SDK фиксируют количество пропущенных спайков или сообщение вроде «Нет спазонов с идентификатором арендатора/агента». Другие сбрасывают их без логировки.

Резолюция:

• Перед экспортом разделы SDK охватываются по идентичности арендатора и агента. Система отбрасывает споведы без ни арендатора, ни агента, и никогда не отправляет их в сервис.
• Убедитесь, BaggageBuilder что вы настроены с идентификатором арендатора и агента перед созданием споведов. Эти значения распространяются через контекст OpenTelemetry и присоединяются ко всем отсекам, созданным в области багажа. Для платформенно-специфичного API см. атрибуты Багаж.
• Убедитесь, что у TurnContext активности есть действительный получатель с идентификатором агента, если вы используете промежуточное ПО, или включите контекстного помощника из интеграционного пакета хостинга для заполнения этих идентификаторов.

Сбой разрешения токена — экспорт пропущен или неавторизован

Симптомы: Резолвер токенов возвращает null или выдает ошибку. В зависимости от SDK экспорт либо полностью пропускается, либо запрос отправляется без авторизационного заголовка и не выполняется с HTTP 401.

Резолюция:

• При инициализации требуется резольвер токенов. Если он отсутствует, экспортер выдает ошибку при запуске. Проверьте, что предоставлен резолвер токенов и возвращает действительный токен носителя.
• Убедитесь, что используются правильные идентификаторы арендатора и идентификатор агента для BaggageBuilder, потому что эти значения передаются токен-резолверу.
• Для агентов, размещённых на Azure, убедитесь, что управляемая идентичность имеет необходимое разрешение API для области наблюдаемости.

HTTP 401 Несанкционированный

Симптомы: Экспорт не удаётся с HTTP 401. Экспортер не повторяет эту ошибку.

Резолюция:

• Проверьте, соответствует ли аудитория токена сфере обзора конечной точки. По умолчанию область действия предназначена https://api.powerplatform.com/.default для агентного агента.
• Убедитесь, что идентификация (управляемая идентичность или регистрация приложения) имеет права на наблюдаемость Агента 365.
• Проверьте, не возвращает ли токен-резолвер делегированный пользовательский токен, токен для неправильной аудитории или истёкший токен.

Это важно

Обновление существующих агентов до этих версий пакетов требует дополнительного шага

Этот шаг применяется только в случае обновления существующего агента. Установка новых агентов не требует этого шага. Если вы обновляетесь до следующих версий пакета или новее, необходимо предоставить новое Agent365.Observability.OtelWrite разрешение вашей личности (управляемая идентификация или регистрация приложения). Без этого разрешения экспорт телеметрии с HTTP 401 не выполняется.

Platform	Минимальная версия требует этого шага
.NET	0.3-beta
Node.js	0.2.0-preview.1
Python	0.3.0

Для необходимых шагов смотрите журнал изменений в пакете, который вы обновляете.

HTTP 403 — запрещено

Симптомы: Экспорт не удаётся с HTTP 403. Экспортер не повторяет эту ошибку.

Резолюция:

• Проверьте, добавлен ли Tenant ID в список разрешённых арендаторов Agent 365 для отслеживания поглощения.
• Убедитесь, что идентификация агента соответствует нужной роли или разрешению для целевого арендатора.

HTTP 429 / 5xx — Временные ошибки

Симптомы: Экспорт не удаётся с временным HTTP-кодом статуса, таким как 429 или 5xx.

Резолюция:

• Эти ошибки обычно временные и разрешаются сами по себе. SDK Python и JavaScript автоматически повторяются на статусных кодах HTTP 408, 429 и 5xx до трёх раз с экспоненциальным отключением. .NET SDK не запускается автоматически.
• Если ошибки сохраняются, проверьте панель управления состоянием сервиса.
• Рассмотрите возможность снижения частоты экспорта, увеличив запланированную задержку между партиями или увеличив максимальный размер экспортной партии. Для вариантов конфигурации по платформам см. Agent365ExporterOptions таблицу в разделе «Конфигурация».

Экспортный тайм-аут

Симптомы: Попытки экспорта выходят за тайм-аут.

Резолюция:

• Проверьте сетевое подключение к конечной точке наблюдаемости.
• Тайм-аут по умолчанию варьируется в зависимости от платформы. Стандартный тайм-аут HTTP-запроса — 30 секунд. Некоторые SDK также имеют отдельный общий тайм-аут для экспортера, который охватывает весь экспортный цикл, включая повторные периоды. Точные свойства и параметры по умолчанию для каждой платформы смотрите Agent365ExporterOptions таблицу в разделе Конфигурация.
• Если тайм-ауты случаются часто, увеличьте соответствующее значение тайм-аута в вариантах экспортера.

Экспорт успешен, но телеметрия отсутствует в Defender или Purview

Симптомы: Логи показывают успешный экспорт, но телеметрия не видна в Microsoft Defender или Microsoft Purview.

Резолюция:

• Убедитесь, что вы соответствуете требованиям для просмотра экспортированных логов. Для Purview аудит должен быть включен. Для Defender необходимо настроить продвинутую охоту. Для получения дополнительной информации см. раздел «Просмотр экспортированных логов».
• Телеметрия может заполняться за несколько минут после успешного экспорта. Дождитесь появления данных, прежде чем продолжать расследование.

Чтобы узнать больше о наблюдаемости тестирования, см.:

• Руководство по тестированию — просмотр журналов наблюдаемости
• Конфигурация наблюдаемости