Устаревший SDK наблюдаемости агента 365

Это важно

В этой статье документируется устаревший SDK Agent 365 Observability. Существующие интеграции продолжают работать, но не используйте этот SDK для новых интеграций. Для новых разработок используйте дистрибутив Microsoft OpenTelemetry. Перед обновлением существующей интеграции ознакомьтесь с руководством по миграции для вашего языка:

• Руководство по миграции Python
• Руководство по миграции для JavaScript/TypeScript
• Руководство по миграции .NET

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

Note

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

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

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

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

Поддерживаемые агенты

Следующие типы агентов поддерживают наблюдаемость Agent 365:

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

Installation

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

Python

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

JavaScript

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

.NET

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

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

Если ваш агент использует NuGet-пакет Microsoft.Agents.A365.Observability.Hosting, установите пакет интеграции с хостингом. Он предоставляет ПО промежуточного слоя, которое автоматически заполняет багаж из 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

Configuration

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

Python

Установите переменную среды ENABLE_A365_OBSERVABILITY_EXPORTER в значение true, чтобы использовать наблюдаемость. В Agent 365 SDK 2.0 и более поздних версиях экспортер всегда использует маршрут service-to-service (S2S) и аутентифицируется с помощью настроенного приложения только token_resolver. Если включить экспортер без резолвера, Python сохраняет резервный вариант консольного экспортера и не отправляет телеметрию в Agent 365.

from microsoft_agents_a365.observability.core import configure

def token_resolver(agent_id: str, tenant_id: str) -> str | None:
    # Return a validated app-only observability token for this agent and tenant.
    return "<app-only-observability-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().

Parameter	Description	Default
logger_name	Имя средства ведения журналов Python, используемого для отладки и вывода содержимого журналов в консоль.	microsoft_agents_a365.observability.core
exporter_options	Экземпляр Agent365ExporterOptions, предназначенный для совместной настройки разрешителя токенов и категории кластера.	None
suppress_invoke_agent_input	Когда этот параметр имеет значение True, входящие сообщения в спанах InvokeAgent подавляются.	False

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

Property	Description	Default
use_s2s_endpoint	Не рекомендуется и игнорируется. Agent 365 SDK 2.0 и более поздние версии всегда используют маршрут S2S, даже если это значение равно False.	False (игнорируется)
max_queue_size	Максимальный размер очереди для процессора пакетной обработки.	2048
scheduled_delay_ms	Задержка в миллисекундах между пакетами экспорта.	5000
exporter_timeout_ms	Тайм-аут в миллисекундах для операции экспорта.	30000
max_export_batch_size	Максимальный размер пакета для экспортных операций.	512

JavaScript

Установите переменную среды ENABLE_A365_OBSERVABILITY_EXPORTER в значение true, чтобы использовать наблюдаемость. В Agent 365 SDK 2.0 и более поздних версиях экспортер всегда использует маршрут S2S и аутентифицируется с помощью настроенного токен-резолвера только для приложения. Если включить экспортер Agent 365 без резольвера, настройка не работает.

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

// Define a token resolver that returns a validated app-only observability token.
const tokenResolver = (agentId, tenantId) => {
    // Your app-only 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.

Property	Description	Default
useS2SEndpoint	Не рекомендуется и игнорируется. Agent 365 SDK 2.0 и более поздние версии всегда используют маршрут S2S, даже если это значение равно false.	true (игнорируется)
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. В Agent 365 SDK 2.0 и более поздних версиях экспортер всегда использует маршрут S2S и аутентифицируется с помощью настроенного токен-резолвера только для приложения. Если вы включите экспортер без TokenResolver или ContextualTokenResolver, конфигурация экспортера не работает.

Добавьте 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) =>
            {
                // Return a cached, validated app-only observability token for this agent and tenant.
                var token = await tokenProvider.GetObservabilityTokenAsync(agentId, tenantId);
                return token;
            }
        };
    });

builder.AddA365Tracing();

Вы можете настроить поведение экспортера, передав делегат настройки и тип экспортера в AddA365Tracing().

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

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

Property	Description	Default
UseS2SEndpoint	Не рекомендуется и игнорируется. Agent 365 SDK 2.0 и более поздние версии всегда используют маршрут S2S, даже если это значение равно false.	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 в пакете 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 в каждом обработчике активности.

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)

Промежуточное ПО пропускает настройку багажа для асинхронных ответов (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 });

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

.NET

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

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

adapter.Use(new BaggageTurnMiddleware());

Промежуточное ПО пропускает настройку багажа для асинхронных ответов (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);
});

Разрешитель токенов

Когда вы используете экспортер Agent 365 в Agent 365 SDK 2.0 и более поздних версиях, предоставите резольвер токенов, который возвращает финальный токен наблюдаемости только для приложения для экземпляра экспортирующего агента. Экспортер всегда отправляет телеметрию на маршрут S2S и не возвращается к делегированному маршруту. Для экспорта по этому маршруту для регистрации агента 365 экземпляру агента не требуется Agent365.Observability.OtelWrite разрешение или согласие администратора.

Используйте двухэтапный обмен Federated Managed Identity (FMI), чтобы получить токен только для приложения:

1. Получите токен blueprint client_credentials для api://AzureADTokenExchange/.default с fmi_path установленным на идентификатор клиента экземпляра агента.
2. Получите токен agent-instance client_credentials для api://9b975845-388f-4429-889e-eab1ef63949c/.default. Передайте жетон шага 1 как client_assertion, и установите client_assertion_type на urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Для полной настройки аутентификации см. Agent 365-enabled using S2S. Полные реализации сервисов токенов см. образцы Agent 365 для Node.js, Python и .NET.

Ваш резолвер должен:

• Вернуть токен только для приложения для экземпляра экспортного агента и арендатора. Никогда не возвращайте утверждение промежуточного чертежа, токена blueprint, пользовательского токена или токена OBO.
• Проверьте токен до того, как он вернёт его. Примите idtyp=app. Если idtyp отсутствует, принимаем только токен с непустым roles притязанием или непустым oid утверждением, равным sub. Отклоняйте токены с scp претензией или иной idtyp стоимостью, истёкшие токены и токены, у которых aud нет 9b975845-388f-4429-889e-eab1ef63949c или api://9b975845-388f-4429-889e-eab1ef63949c.
• Кэшируйте токен и обновляйте его до истечения срока действия. Экспортер вызывает резолвер один раз для каждого идентификатора арендатора и агента в каждой экспортной партии.

Note

Миграция с SDK 1.x: SDK 2.0 удаляет делегированный обмен токенами для экспорта наблюдаемости. Замените делегированный код токена в вашем агенте на резолвер только для приложения, как показано в следующих примерах. Агенты, которые остаются на SDK 1.x и экспортируют по делегированному маршруту, всё равно нуждаются в делегированном Agent365.Observability.OtelWrite разрешении и согласии администратора. Команда не настраивает это разрешение для агентов a365 setup all blueprint. Чтобы предоставить его, см. Дать разрешение.

Python

Звонок AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, acquire_app_only_obs_token) из вашего token_resolver. Кэш передаёт область видимости /.default вашему callback и возвращает кэшированный токен.

from microsoft_agents_a365.observability.core import configure
from microsoft_agents_a365.observability.hosting.token_cache_helpers import AgenticTokenCache

cache = AgenticTokenCache()

async def acquire_app_only_obs_token(
    agent_id: str,
    tenant_id: str,
    scopes: list[str],
) -> str:
    # Run the FMI exchange described earlier, validate the token, and return it.
    return "<app-only-observability-token>"

async def token_resolver(agent_id: str, tenant_id: str) -> str:
    return await cache.refresh_observability_token(
        agent_id, tenant_id, acquire_app_only_obs_token
    )

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

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

Для миграции с SDK 1.x удалите AGENT_APP.auth.exchange_token вызов, запрашивавший область видимости, и AgenticTokenCache.register_observability вызов, проходящий AgenticTokenStruct. В SDK 2.0 register_observability — устаревший no-op.

JavaScript

Используйте withTokenResolver с AgenticTokenCacheInstance.RefreshObservabilityToken(agentId, tenantId, acquireAppOnlyObsToken). Обратный вызов приобретения получает (agentId, tenantId, scopes) и возвращает окончательный токен наблюдаемости только для приложения. Читайте кэшированный токен с AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId).

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

async function acquireAppOnlyObsToken(
  agentId: string,
  tenantId: string,
  scopes: readonly string[]
): Promise<string> {
  // Run the FMI exchange described earlier, validate the token, and return it.
  return "<app-only-observability-token>";
}

const builder = ObservabilityManager.configure(builder =>
  builder
    .withService('my-agent-service', '1.0.0')
    .withTokenResolver(async (agentId, tenantId) => {
      await AgenticTokenCacheInstance.RefreshObservabilityToken(
        agentId, tenantId, acquireAppOnlyObsToken
      );
      return AgenticTokenCacheInstance.getObservabilityToken(agentId, tenantId);
    })
);

builder.start();

Для миграции с SDK 1.x удалите agentApplication.authorization.exchangeToken вызов, запрашивавший область видимости, и замените RefreshObservabilityToken(agentId, tenantId, context, authorization, scopes) его формой резольвера из примера. SDK 2.0 устраняет делегированную перегрузку: вызывающие TypeScript получают ошибку компиляции, а нетипированные — одноразовый журнал ошибок без токена.

.NET

Используйте AddAgenticTracingExporter() для регистрации IExporterTokenCache<ObservabilityTokenResolver> и экспорта опций, которые считывают токены из кэша.

using Microsoft.Agents.A365.Observability.Hosting;

builder.Services.AddAgenticTracingExporter();

В приложении агента зарегистрируйте резолвер только для приложения для агента и арендатора, вызвав RegisterObservability(agentId, tenantId, resolver, scopes). Первая регистрация агента и арендатора выигрывает.

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

public class MyAgent : AgentApplication
{
    private readonly IExporterTokenCache<ObservabilityTokenResolver> _agentTokenCache;

    public MyAgent(AgentApplicationOptions options, IExporterTokenCache<ObservabilityTokenResolver> agentTokenCache)
        : base(options)
    {
        _agentTokenCache = agentTokenCache;
    }

    protected async Task MessageActivityAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
    {
        var agentId = turnContext.Activity.Recipient.AgenticAppId;
        var tenantId = turnContext.Activity.Recipient.TenantId;

        _agentTokenCache.RegisterObservability(
            agentId,
            tenantId,
            AcquireAppOnlyObservabilityTokenAsync,
            EnvironmentUtils.GetObservabilityAuthenticationScope());

        using var baggageScope = new BaggageBuilder()
            .TenantId(tenantId)
            .AgentId(agentId)
            .Build();

        // Handle the message.
    }

    private static Task<string?> AcquireAppOnlyObservabilityTokenAsync(
        string agentId,
        string tenantId,
        string[] observabilityScopes)
    {
        // Run the FMI exchange described earlier, validate the token, and return it.
        return Task.FromResult<string?>("<app-only-observability-token>");
    }
}

Если вы управляете AgenticTokenCache экземпляром напрямую, вызовите RefreshObservabilityToken(agentId, tenantId, resolver) , чтобы использовать стандартную область видимости или RefreshObservabilityToken(agentId, tenantId, resolver, scopes) специально передавать область видимости.

Чтобы перенести с SDK 1.x, замените IExporterTokenCache<AgenticTokenStruct> и прошедший RegisterObservabilityAgenticTokenStruct вызов на резолвер только для приложения, указанный в примере. Не используйте ExchangeTurnTokenAsync для экспорта наблюдаемости. В SDK 2.0 AgenticTokenStruct перегрузка регистрации устарела и вызывает ошибку компиляции.

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

Автоматическое инструментирование слушает сигналы телеметрии агентских фреймворков (SDK) для трассировок и перенаправляет их в службу наблюдаемости Agent 365. Эта функция избавляет разработчиков от необходимости вручную писать код для мониторинга, упрощает настройку и обеспечивает последовательное отслеживание производительности.

Это важно

Автоинструментирование заполняет только стандартные атрибуты OTel. Вы должны добавить атрибуты, характерные для Microsoft, через BaggageBuilder. Чтобы определить, какие атрибуты отсутствуют, сверьте вывод спанов в консоли с журналами магазина, чтобы выявить различия.

Различные SDK и платформы поддерживают автоинструментирование:

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

Note

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

Семантическое ядро

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

Семантический ядро не поддерживается в 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>,
          ...
      };
    }
}

OpenAI

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

Note

Автоматическое инструментирование для платформы LangChain также поддерживает LangGraph и Deep Agent. То же самое расширение автоматически фиксирует телеметрию для агентов, построенных с использованием любой из этих платформ.

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

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. Это значение обеспечивает экспорт спанов (трассировок) в консоль.

Для выявления причин сбоев при экспорте включите подробное ведение журнала, установив переменную среды 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. Это значение обеспечивает экспорт спанов (трассировок) в консоль.

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

# 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. Это значение обеспечивает экспорт спанов (трассировок) в консоль.

Чтобы расследовать сбои при экспорте, настройте подробное ведение журнала в 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.

Note

Если вы не зарегистрируете 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"
    }

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

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

Проверка

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

Troubleshooting

Этот раздел посвящен распространенным проблемам при реализации и использовании наблюдаемости.

Проблема.	Description
Данные о наблюдаемости не отображаются	Телеметрия не отображается, потому что экспортирование не настроено, конфигурация некорректна или разрешение токена завершилось сбоем.
Отсутствует ИД арендатора или ИД агента - спаны пропущены	Перед экспортом спаны отбрасываются, если отсутствуют идентификационные атрибуты, необходимые для разделения.
Ошибка разрешения маркера — экспорт пропущен или неавторизован	Экспорт не проходит, если резолвер не возвращает токен или сталкивается с исключением.
Http 401 Несанкционированный доступ	Аутентификация проходит синтаксически успешно, но токен недействителен для приема данных из-за области, типа или истечения срока действия.
HTTP 403 Запрещено	Доступ запрещается из-за пробелов в лицензировании арендаторов, отсутствия регистрации агента 365 или отсутствия разрешения на наблюдаемость, если это необходимо.
HTTP 403 Forbidden — несоответствие идентификатора агента	Запрос отклоняется, если идентификатор агента в URL-адресе не совпадает с идентификатором, указанным в токене.
Ошибки HTTP 429 или 5xx — временные ошибки	Временное ограничение пропускной способности или сбои на стороне службы прерывают экспорт и могут потребовать настройки повторных попыток.
Истечение времени ожидания экспорта	Пакеты телеметрии превышают заданное время ожидания из-за сетевой задержки или медленного ответа конечных точек.
Экспорт успешно выполнен, но телеметрия не отображается в Defender или Purview	Прием данных завершен, но дальнейшая видимость задерживается или блокируется из-за невыполнения предварительных условий по наличию продуктов.

Tip

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

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

Симптомы:

• Агент запущен
• В административном центре нет телеметрии
• Активность агента не отображается

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

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

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

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

  Необходимо явно включить экспортер Agent 365. Если он отключен, SDK возвращается к консольному экспортеру, и телеметрия не отправляется в службу. Сведения о настройке см. в разделе Конфигурация.

• Проверьте конфигурацию сопоставителя маркеров

  Экспортеру нужен действительный резолвер токенов, который возвращает токен наблюдаемости только для приложения для каждого экспортного запроса. Если резолвер отсутствует, не возвращает токен или отправляет запрос, экспорт не отправляет запрос. Убедитесь, что ваш код реализует токен-резолвер. Подробнее см. в разделе Разрешитель токенов.

• Проверьте журналы на наличие ошибок

  Включите расширенное ведение журнала и используйте команду 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 записывают в журнал количество пропущенных спанов или выводят сообщение, например "Не найдено спанов с идентификатором арендатора/агента"; другие пропускают их без занесения в журнал.

Решение:

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

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

Симптомы: Резолвер токенов возвращает null, возвращает пустой токен или выдает ошибку. Экспорт проваляется без отправки запроса, и экспортер не возвращается к делегированному маршруту.

Решение:

• Предоставить резолвер, который возвращает окончательный токен наблюдаемости только для приложения для экземпляра экспортирующего агента и арендатора.
• Проверьте, что для BaggageBuilder используются правильные идентификаторы арендатора и агента, так как эти значения передаются разрешителю токенов.
• Проверьте поведение стартапа, специфичного для языка. Node.js не выполняет конфигурацию, когда экспортер Agent 365 включён без резолвера, .NET не работает с конструированием экспортера, и Python возвращается к консольному экспортеру, когда резолвер не настроен.
• Убедитесь, что ваш резолвер проверяет токен перед его возвратом. Он должен отклонять делегированные жетоны с scp претензией и жетоны, выданные для неправильной аудитории.

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

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

Решение:

• Проверьте, что аудитория токенов — это 9b975845-388f-4429-889e-eab1ef63949c или api://9b975845-388f-4429-889e-eab1ef63949c.
• Проверьте, не возвращает ли токен-резолвер делегированный пользовательский токен, токен с scp претензией, токен для неправильной аудитории или истёкший токен.
• Убедитесь, что резолвер возвращает окончательный токен agent-instance, а не промежуточное утверждение чертежа.

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

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

Основная причина: Ошибка HTTP 403 может быть вызвана различными причинами. Проверьте следующие разрешения по порядку.

Решение:

• Отсутствующая лицензия — Проверьте, что вашему арендатору назначена одна из следующих лицензий в Центре администрирования Microsoft 365:

  • Тест - Microsoft 365 E7
  • Microsoft 365 E7
  • Microsoft Agent 365 Frontier

• Экземпляр агента не зарегистрирован — Маршрут S2S принимает токен только для приложения без роли Agent365.Observability.OtelWrite только из агента, зарегистрированного в Agent 365. В противном случае он возвращает HTTP 403 insufficient_scope. Для blueprint агентов a365 setup all регистрируется экземпляр агента. Чтобы попробовать повторить неудачную регистрацию, забегайте a365 setup all --agent-registration-only. Создание идентичности Microsoft Entra само по себе не регистрирует экземпляр агента.

• Токен не предназначен только для приложения — проверьте, не содержит ли токен претензии scp . Маршрут S2S требует токена только для приложения.

• Незарегистрированная личность не имеет роли приложения — незарегистрированные личности, включая стандартные регистрации приложений, используемые пользовательскими агентами движка, нуждаются в роли Agent365.Observability.OtelWrite приложения. Чтобы предоставить его, см. Дать разрешение.

• Агент SDK 1.x на делегированном маршруте — Делегированный маршрут требует делегированного Agent365.Observability.OtelWrite разрешения и согласия администратора, что a365 setup all не настраивается для blueprint agents. Обновитесь до SDK 2.0 или дайте разрешение.

• Agent ID не совпадает с токеном — см. HTTP 403 Forbidden - Несоответствие ID агента.

HTTP 403 Forbidden — несоответствие идентификатора агента

Симптомы: Экспорт завершился ошибкой HTTP 403 и серверным сообщением, аналогичным 403 Forbidden с agent-ID-mismatch ошибками при обращении к конечным точкам трассировки Agent 365.

Основная причина: эта ошибка возникает, если используется идентификатор клиента схемы вместо идентификатора клиента экземпляра агента при настройке сведений об агенте. Идентификатор агента в URL экспорта не соответствует идентификатору, авторизованному маркером, поэтому конечная точка трассировки отклоняет запрос.

Решение:

• Убедитесь, что идентификатор арендатора добавлен в список разрешённых арендаторов Agent 365.
• Задайте сведения об агенте с идентификатором клиента экземпляра агента (а не идентификатором клиента схемы).
• Проверьте сгенерированный URL для экспорта — он записывается в журнал при включённом ведении журнала. Убедитесь, что идентификатор агента в URL совпадает с идентификатором клиента экземпляра агента.
• Чтобы включить журнал ведения диагностики для SDK, см. Локальная проверка.

Ошибки 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 необходимо настроить расширенную охоту. Дополнительные сведения см. в разделе Просмотр экспортированных журналов.
• Появление данных телеметрии после успешного экспорта может занять несколько минут. Дождитесь появления данных, прежде чем приступать к дальнейшему изучению проблемы.

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

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

Связанные материалы

• Концепции наблюдаемости Agent 365 — потоки данных, модели идентификации, аутентификация, области действия и ограничения, применяемые ко всем путям интеграции.
• Справочник атрибутов наблюдаемости Agent 365 — каноническая схема атрибутов спана, которой должен соответствовать каждый спан, поступающий в Agent 365.
• Microsoft OpenTelemetry Distro — рекомендуемый унифицированный SDK для новых интеграций.