SDK наблюдаемости

Важно

Чтобы включить наблюдаемость в Agent 365, используйте Microsoft OpenTelemetry Distro. Этот дистрибутив предоставляет единый пакет SDK наблюдаемости, который лежит в основе Agent 365, Microsoft Foundry, Azure Monitor и других продуктов Майкрософт. Существующий подход, описанный в этой статье, продолжает работать без нарушений совместимости. Рекомендации по миграции по языкам см. в следующих руководствах:

Примечание

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

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

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

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

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

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

Установка

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

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

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

Если ваш агент использует пакет Microsoft Agents Hosting, установите пакет интеграции с хостингом. Он предоставляет ПО промежуточного слоя, которое автоматически заполняет багаж и области из TurnContext, а также включает кэширование токенов для экспортера наблюдаемости.

pip install microsoft-agents-a365-observability-hosting

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

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

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

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

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

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

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

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

from microsoft_agents_a365.observability.core import configure

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

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

Разрешитель токенов исключается из ведения журналов, передаваемых в консоль.

Вы можете настроить поведение экспортера, передав экземпляр Agent365ExporterOptions в exporter_options. Когда exporter_options указан, он имеет приоритет над параметрами token_resolver и cluster_category.

from microsoft_agents_a365.observability.core import configure, Agent365ExporterOptions

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

В следующей таблице описываются необязательные параметры для configure().

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

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

Свойство Описание По умолчанию
use_s2s_endpoint При True используется путь конечной точки «служба-служба» (service-to-service). False
max_queue_size Максимальный размер очереди для процессора пакетной обработки. 2048
scheduled_delay_ms Задержка в миллисекундах между пакетами экспорта. 5000
exporter_timeout_ms Тайм-аут в миллисекундах для операции экспорта. 30000
max_export_batch_size Максимальный размер пакета для экспортных операций. 512

Атрибуты багажа

Используйте BaggageBuilder для установки контекстной информации, которая передаётся через все спаны в запросе. SDK реализует SpanProcessor, который копирует все непустые записи багажа в только что начатые спаны, не перезаписывая существующие атрибуты.

from microsoft_agents_a365.observability.core import BaggageBuilder

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

Для автоматического заполнения BaggageBuilder из TurnContext используйте вспомогательную функцию populate из пакета microsoft-agents-a365-observability-hosting. Этот вспомогательный метод автоматически извлекает из действия сведения о вызывающем абоненте, агенте, арендаторе, канале и беседе.

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

builder = BaggageBuilder()
populate(builder, turn_context)

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

Промежуточное ПО для багажа

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

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

from microsoft_agents_a365.observability.hosting import BaggageMiddleware

adapter.use(BaggageMiddleware())

В качестве альтернативы используйте ObservabilityHostingManager для настройки ПО промежуточного слоя для багажа вместе с другими функциями хостинга:

from microsoft_agents_a365.observability.hosting import ObservabilityHostingManager, ObservabilityHostingOptions

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

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

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

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

В следующем примере показано, как сгенерировать токен с помощью SDK microsoft_agents.hosting.core. Сгенерированный здесь токен аутентификации используется для экспорта спанов в службу приема данных A365. Агенты могут самостоятельно генерировать токен, например с помощью Microsoft Authentication Library (MSAL), но им необходимо удостовериться, что токен содержит область наблюдаемости.

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

agents_sdk_config = load_configuration_from_env(environ)

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

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

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

Для построенного с помощью A365 CLI агента, который использует ИИ-коллегу и пакет Microsoft Agent 365 Observability Hosting Library, используйте AgenticTokenCache для автоматического кэширования токенов. Зарегистрируйте токен один раз для каждого агента и арендатора в обработчике активности и передайте cache.get_observability_token в качестве token_resolver в вашей конфигурации наблюдаемости.

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

# Create a shared cache instance
token_cache = AgenticTokenCache()

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

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

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

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

Важно

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

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

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

Примечание

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

Semantic Kernel

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

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

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

Настройте наблюдаемость.

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

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

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

# Your Semantic Kernel code is now automatically traced

OpenAI

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

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

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

Настройте наблюдаемость.

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

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

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

# Your OpenAI Agents code is now automatically traced

Agent Framework

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

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

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

Настройте наблюдаемость.

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

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

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

Фреймворк LangChain

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

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

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

Настройте наблюдаемость.

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

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

# Enable auto-instrumentation
CustomLangChainInstrumentor()

# Your LangChain code is now automatically traced

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

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

Вызов агента

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

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

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

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

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

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

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

Выполнение инструмента

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

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)

Вывод

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

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)

Выход

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

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

Локальная проверка

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

Установите переменную среды ENABLE_A365_OBSERVABILITY_EXPORTER в значение false. Это значение обеспечивает экспорт спанов (трассировок) в консоль.

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

import logging

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

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

Ключевые сообщения журнала:

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

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

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

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

Важно

Для успешного прохождения проверки перед публикацией в магазине в вашем агенте должны быть реализованы области 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
  • Выберите вашего агента > Активность
  • Вы видите сеансы и вызовы инструментов

Устранение неполадок

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

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

Совет

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

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

Симптомы:

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

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

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

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

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

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

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

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

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

    Включите расширенное ведение журнала и используйте команду az webapp log tail для поиска в журналах ошибок, связанных с наблюдаемостью. Подробнее о том, как включить ведение журнала для каждой платформы, см. в разделе Локальная проверка.

    # Look for observability-related errors
az webapp log tail --name <your-app-name> --resource-group <your-resource-group> | Select-String "observability"

  • Убедитесь, что телеметрия экспортируется

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

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

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

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

Решение:

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

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

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

Решение:

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

HTTP 401 Не авторизовано

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

Решение:

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

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

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

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

Решение:

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

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

  • Отсутствует разрешение Agent365.Observability.OtelWrite — если вы недавно обновили пакеты наблюдаемости, необходимо предоставить это разрешение. См. важное примечание в следующем разделе.

Важно

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

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

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

Предоставьте разрешение, используя один из следующих вариантов.

Вариант A — Agent 365 CLI (требуется учетная запись глобального администратора; запуск из каталога проекта агента, содержащего a365.config.json, или используйте --agent-name)

a365 setup permissions bot

Или без конфигурационного файла:

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

Эта команда назначает все отсутствующие разрешения в схеме, включая области наблюдаемости.

Вариант B — портал Entra (файлы конфигурации не требуются; требуется доступ глобального администратора к регистрации приложения схемы)

  1. Перейдите на Entra portal>Регистрации приложений> и выберите ваше приложение Blueprint.
  2. Перейдите в API разрешения>Добавить разрешение>API, используемые моей организацией,> и выполните поиск по 9b975845-388f-4429-889e-eab1ef63949c.
  3. Выберите Делегированные разрешения>, проверьте Agent365.Observability.OtelWrite>Добавить разрешения.
  4. Повторите шаги 2–3; на этот раз выберитеРазрешения приложения> отметьте Agent365.Observability.OtelWrite>Добавить разрешения.
  5. Щёлкните Предоставить согласие администратора и подтвердите.

И Agent365.Observability.OtelWrite (Делегировано), и Agent365.Observability.OtelWrite (Приложение) должны иметь статус Granted.

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

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

Связанный контент

  • Last updated on