Observability

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

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

Интеграция OpenTelemetry

Agent Framework интегрируется с OpenTelemetry, а в частности агентная платформа выдает трассировки, журналы и метрики в соответствии с семантические соглашения OpenTelemetry GenAI.

Включение наблюдаемости (C#)

Чтобы включить наблюдаемость для клиента чата, необходимо создать клиент чата следующим образом:

// Using the AIProjectClient as an example
var instrumentedChatClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName) // Converts into a Microsoft.Extensions.AI.IChatClient
    .AsBuilder()
    .UseOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true)    // Enable OpenTelemetry instrumentation with sensitive data
    .Build();

Предупреждение

DefaultAzureCredential удобно для разработки, но требует тщательного рассмотрения в рабочей среде. В рабочей среде рекомендуется использовать определенные учетные данные (например, ManagedIdentityCredential), чтобы избежать проблем с задержкой, непреднамеренной проверки данных аутентификации и потенциальных рисков безопасности из-за резервных механизмов.

Чтобы включить наблюдаемость для агента, необходимо создать агент следующим образом:

var agent = new ChatClientAgent(
    instrumentedChatClient,
    name: "OpenTelemetryDemoAgent",
    instructions: "You are a helpful assistant that provides concise and informative responses.",
    tools: [AIFunctionFactory.Create(GetWeatherAsync)]
)
    .AsBuilder()
    .UseOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true) // Enable OpenTelemetry instrumentation with sensitive data
    .Build();

Это важно

При включении наблюдаемости для клиентов и агентов чата может отображаться повторяющаяся информация, особенно при включении конфиденциальных данных. Контекст чата (включая запросы и ответы), захваченный клиентом чата и агентом, будет включен в оба диапазона. В зависимости от ваших потребностей вы можете включить наблюдаемость только в клиенте чата или только на агенте, чтобы избежать дублирования. Дополнительные сведения об атрибутах, захваченных для LLM и агентов, см. в семантических соглашениях GenAI .

Предупреждение

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

Configuration

Теперь, когда клиент чата и агент инструментируются, вы можете настроить экспортеров OpenTelemetry для отправки данных телеметрии в нужную серверную часть.

Traces

Чтобы экспортировать трассировки в нужную серверную часть, можно настроить пакет SDK OpenTelemetry в коде запуска приложения. Например, чтобы экспортировать трассировки в ресурс Azure Monitor:

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Trace;
using OpenTelemetry.Resources;
using System;

// The source name under which all activities, metrics, and logs will be emitted.
const string SourceName = "MyApplication";
const string ServiceName = "AgentOpenTelemetry";

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddAzureMonitorTraceExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Tip

Метод AddSource используется для указания исходного имени, к которому будет прослушивать поставщик. Убедитесь, что оно соответствует исходному имени, используемому в коде инструментирования (например, UseOpenTelemetry(sourceName: SourceName)). Если исходное имя не указано в коде инструментирования, оно по умолчанию будет Experimental.Microsoft.Agents.AI, в этом случае следует использовать AddSource("Experimental.Microsoft.Agents.AI") в конфигурации поставщика трассировки и поставщика счетчиков.

Tip

В зависимости от серверной части можно использовать различные экспортеры. Дополнительные сведения см. в документации .NET OpenTelemetry. Для локальной разработки рекомендуется использовать панель мониторинга Aspire.

Metrics

Аналогичным образом, чтобы экспортировать метрики в нужную серверную часть, можно настроить пакет SDK OpenTelemetry в коде запуска приложения. Например, чтобы экспортировать метрики в ресурс Azure Monitor:

using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using System;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

var resourceBuilder = ResourceBuilder
    .CreateDefault()
    .AddService(ServiceName);

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddAzureMonitorMetricExporter(options => options.ConnectionString = applicationInsightsConnectionString)
    .Build();

Logs

Журналы записываются с помощью используемой платформы ведения журнала, например Microsoft.Extensions.Logging. Чтобы экспортировать журналы в ресурс Azure Monitor, можно настроить поставщика ведения журнала в коде запуска приложения:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Extensions.Logging;

var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
    ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");

using var loggerFactory = LoggerFactory.Create(builder =>
{
    // Add OpenTelemetry as a logging provider
    builder.AddOpenTelemetry(options =>
    {
        options.SetResourceBuilder(resourceBuilder);
        options.AddAzureMonitorLogExporter(options => options.ConnectionString = applicationInsightsConnectionString);
        // Format log messages. This is default to false.
        options.IncludeFormattedMessage = true;
        options.IncludeScopes = true;
    })
    .SetMinimumLevel(LogLevel.Debug);
});

// Create a logger instance for your application
var logger = loggerFactory.CreateLogger<Program>();

Панель мониторинга Aspire

Используйте панель мониторинга Aspire в качестве быстрого способа визуализации трассировок и метрик во время разработки. Дополнительные сведения см. в документации по панели мониторинга Aspire. Панель мониторинга Aspire получает данные через сборщик OpenTelemetry, который можно добавить в поставщик трассировки следующим образом:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource(SourceName)
    .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
    .Build();

Начало работы

Полный пример агента с поддержкой OpenTelemetry в репозитории Agent Framework.

Tip

Полные примеры запуска см. в примерах .NET .

Зависимости

Включенные пакеты

Чтобы включить наблюдаемость в приложении Python, по умолчанию устанавливаются следующие пакеты OpenTelemetry:

Экспортеров

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

Некоторые распространенные экспортеры, которые могут потребоваться установить в зависимости от ваших потребностей:

  • Для поддержки протокола gRPC: установка opentelemetry-exporter-otlp-proto-grpc
  • Для поддержки протокола HTTP: установка opentelemetry-exporter-otlp-proto-http
  • Для приложение Azure Insights: установите azure-monitor-opentelemetry

Используйте реестр OpenTelemetry , чтобы найти больше экспортеров и пакетов инструментирования.

Включение наблюдаемости (Python)

Распространение трассировки MCP

Всякий раз, когда существует активный контекст диапазона OpenTelemetry, Agent Framework автоматически распространяет контекст трассировки на серверы MCP через params._meta поле tools/call запросов. Он использует глобально настроенные распространители OpenTelemetry (контекст трассировки W3C по умолчанию, производство traceparent и tracestate), поэтому также поддерживаются пользовательские распространители (B3, Jaeger и т. д.). Это обеспечивает распределенную трассировку между границами сервера агента в MCP, соответствующую спецификации MCP_meta.

Область: автоматическая _meta внедрение применяется только к сеансам MCP, которые открывает сам процесс агента — MCPStreamableHTTPToolMCPStdioToolи (или MCPWebsocketTool любой другой подкласс, открытый MCPTool клиентом). Он не применяется к конфигурациям инструментов MCP, управляемым поставщиком, таким как , FoundryChatClient.get_mcp_tool(...), OpenAIChatClient.get_mcp_tool(...), AnthropicClient.get_mcp_tool(...)или панели элементов hosted-agent, так как GeminiChatClient.get_mcp_tool(...)в этих случаях tools/call сообщение выдано средой выполнения службы поставщика, а не процессом агента. В результате платформа не имеет возможности внедрить контекст трассировки в эти запросы, и распространение traceparent/tracestate по этой границе размещенной службы является ответственностью среды выполнения службы, а не Agent Framework. Если требуется сквозная распределенная трассировка на подчиненный сервер MCP, используйте открытый клиентом транспорт MCP вместо размещенного соединителя.

Пять шаблонов для настройки наблюдаемости

Мы определили несколько способов настройки наблюдаемости в приложении в зависимости от ваших потребностей:

Самый простой подход — настройка всего с помощью переменных среды:

from agent_framework.observability import configure_otel_providers

# Reads OTEL_EXPORTER_OTLP_* environment variables automatically
configure_otel_providers()

Или если требуется только экспортеры консоли, задайте ENABLE_CONSOLE_EXPORTERS переменную среды:

ENABLE_CONSOLE_EXPORTERS=true

from agent_framework.observability import configure_otel_providers

# Console exporters are enabled via the ENABLE_CONSOLE_EXPORTERS env var
configure_otel_providers()

Вы также можете переопределить параметры экспорта общих служб, ресурсов и OTLP в коде:

from agent_framework.observability import configure_otel_providers

configure_otel_providers(
    service_name="customer-support-agent",
    resource_attributes={
        "deployment.environment.name": "production",
        "service.namespace": "customer-support",
    },
    otlp_endpoint="https://otel.example.com",
    otlp_protocol="http/protobuf",
)

Параметр otlp_protocol принимает grpc, http/protobufили http. Вы также можете задать service_version, otlp_headersotlp_timeout в секундах и otlp_compressiongzipв , deflateили none. Явное имя службы и значения версий имеют приоритет над переменными среды, а resource_attributes также объединяются OTEL_RESOURCE_ATTRIBUTES. Программные параметры OTLP переопределяют их базовые переменные среды. Переменные конечной точки и заголовка, относящиеся к сигналу, остаются более конкретными и otlp_headers заменяют базовые заголовки перед объединением заголовков, относящихся к сигналу. Для HTTP базовая конечная точка автоматически получает /v1/traces/v1/metricsпуть или /v1/logs путь.

2. Настраиваемые экспортеры

Чтобы больше контролировать экспортеров, создайте их самостоятельно и передайте их configure_otel_providers()в:

from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from agent_framework.observability import configure_otel_providers

# Create custom exporters with specific configuration
exporters = [
    OTLPSpanExporter(endpoint="http://localhost:4317", compression=Compression.Gzip),
    OTLPLogExporter(endpoint="http://localhost:4317"),
    OTLPMetricExporter(endpoint="http://localhost:4317"),
]

# These will be added alongside any exporters from environment variables
configure_otel_providers(exporters=exporters, enable_sensitive_data=True)

3. Сторонняя настройка

Многие сторонние пакеты OpenTelemetry имеют собственные методы установки. Эти методы можно использовать сначала, а затем вызвать enable_instrumentation() путь к коду инструментирования Agent Framework:

from azure.monitor.opentelemetry import configure_azure_monitor
from agent_framework.observability import create_resource, enable_instrumentation

# Configure Azure Monitor first
configure_azure_monitor(
    connection_string="InstrumentationKey=...",
    resource=create_resource(),  # Uses OTEL_SERVICE_NAME, etc.
    enable_live_metrics=True,
)

# Then activate Agent Framework's telemetry code paths
# This is optional if ENABLE_INSTRUMENTATION and/or ENABLE_SENSITIVE_DATA are set in env vars
enable_instrumentation(enable_sensitive_data=False)

Для Langfuse:

from agent_framework.observability import enable_instrumentation
from langfuse import get_client

langfuse = get_client()

# Verify connection
if langfuse.auth_check():
    print("Langfuse client is authenticated and ready!")

# Then activate Agent Framework's telemetry code paths
enable_instrumentation(enable_sensitive_data=False)

4. Настройка вручную

Для полного управления можно вручную настроить экспортеров, поставщиков и инструментирование. Используйте вспомогательную функцию create_resource() , чтобы создать ресурс с соответствующим именем и версией службы. Подробные инструкции по инструментированию вручную см. в документации Python OpenTelemetry.

5. Автоматическое инструментирование (нулевой код)

Используйте средство КОМАНДНОй строки OpenTelemetry для автоматического инструментирования приложения без изменений кода:

opentelemetry-instrument \
    --traces_exporter console,otlp \
    --metrics_exporter console \
    --service_name your-service-name \
    --exporter_otlp_endpoint 0.0.0.0:4317 \
    python agent_framework_app.py

Дополнительные сведения см. в документации OpenTelemetry Zero-Python code.

Использование трассировок и счетчиков

После настройки наблюдаемости можно создать настраиваемые диапазоны или метрики:

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # do something
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Это оболочки API OpenTelemetry, возвращающие трассировку или метрика от глобального поставщика, с agent_framework заданным именем библиотеки инструментирования по умолчанию.

Переменные среды

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

  • ENABLE_INSTRUMENTATION — Значение по умолчанию — значение true;, чтобы false отключить инструментирование OpenTelemetry.
  • ENABLE_SENSITIVE_DATA— Значение по умолчанию — falsetrue для включения ведения журнала конфиденциальных данных (запросы, ответы, аргументы вызова функции и результаты). Будьте осторожны с этим параметром, так как он может предоставлять конфиденциальные данные.
  • ENABLE_MESSAGE_EVENTS— Значение по умолчанию — trueзначение true, yes1или on включение событий журнала сообщений версии 1.36 и событий журнала выбора, без учета регистра. Любое другое значение набора отключает их. Эти события создаются только при включении инструментирования и конфиденциальных данных.
  • ENABLE_CONSOLE_EXPORTERS— Значение по умолчанию — для falsetrue включения выходных данных консоли для телеметрии.
  • VS_CODE_EXTENSION_PORT — порт для набора средств ИИ Microsoft или интеграция расширения Vs Code для Foundry VS Code.
  • OTEL_SEMCONV_STABILITY_OPT_IN — При отмене настройки Агент Framework использует последние экспериментальные соглашения GenAI. Если задано, включите маркер с учетом gen_ai_latest_experimental регистра в значение, разделенное запятыми, чтобы использовать последние соглашения. Значение набора, которое пропускает этот маркер, включая пустое значение, выбирает соглашения версии 1.36.

Атрибуты диапазона последней версии 36 выдаются gen_ai.provider.name; атрибуты диапазона версии 1.36 и события сообщения выдаются gen_ai.system. Выбор события сообщения не зависит от выбора семантического соглашения. Выбор версии 1.36 подавляет последние атрибуты диапазона сообщений, но не отключает события сообщения версии 1.36. Если конфиденциальные данные включены, последний режим по умолчанию выдает оба представления.

Agent Framework также добавляет свой пакет и версию в User-Agent поддерживаемых клиентских запросов. Утвержденные Microsoft Foundry и Azure пути запросов OpenAI могут включать маркер использования функций на уровне процесса, который кодирует категории функций платформы, а не содержимое запроса или ответа. Задайте эти переменные перед началом процесса:

  • AGENT_FRAMEWORK_FEATURE_MASK_DISABLED=true — отключает только маркер использования компонентов и сохраняет пакет или версию user-agent.
  • AGENT_FRAMEWORK_USER_AGENT_DISABLED=true — отключает весь вклад в агентную платформу User-Agent, включая маркер компонента.

Предупреждение

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

Стандартные переменные среды OpenTelemetry

Функция configure_otel_providers() автоматически считывает стандартные переменные среды OpenTelemetry:

Конфигурация OTLP (для панели мониторинга Aspire, Jaeger и т. д.):

  • OTEL_EXPORTER_OTLP_ENDPOINT — базовая конечная точка для всех сигналов (например, http://localhost:4317)
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT — конечная точка трассировки (переопределяет базовую)
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT — конечная точка для конкретных метрик (переопределяет базовую)
  • OTEL_EXPORTER_OTLP_LOGS_ENDPOINT — конечная точка для определенных журналов (переопределяет базовую)
  • OTEL_EXPORTER_OTLP_PROTOCOL — протокол для использования (grpc или http, по умолчанию: grpc)
  • OTEL_EXPORTER_OTLP_HEADERS — заголовки для всех сигналов (например, key1=value1,key2=value2)

Идентификация службы:

  • OTEL_SERVICE_NAME — имя службы (по умолчанию: agent_framework)
  • OTEL_SERVICE_VERSION — версия службы (по умолчанию: версия пакета)
  • OTEL_RESOURCE_ATTRIBUTES - Дополнительные атрибуты ресурсов

Дополнительные сведения см. в спецификации OpenTelemetry .

настройка Microsoft Foundry

Microsoft Foundry поддерживает встроенную поддержку трассировки с визуализацией для диапазонов.

Убедитесь, что у вас настроен экземпляр Foundry с Azure Monitor, см. раздел details

Установите пакет azure-monitor-opentelemetry.

pip install azure-monitor-opentelemetry

Настройка наблюдаемости непосредственно из FoundryChatClient

Для проектов Foundry можно настроить наблюдаемость непосредственно из FoundryChatClientследующих объектов:

import os

from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential

async def main():
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=credential,
        )

        # Automatically configures Azure Monitor with the connection string from the Foundry project
        await client.configure_azure_monitor(enable_live_metrics=True)

Tip

Аргументы для client.configure_azure_monitor() передаются в базовую функцию configure_azure_monitor() из пакета azure-monitor-opentelemetry см. в разделе документации подробные сведения о настройке строка подключения и ресурса.

Настройка Azure Monitor и включение инструментирования

Сведения о проектах, отличных от Foundry, с помощью Application Insights, см. в разделе сведений о настройке пользовательского агента в Foundry.

Затем запустите агент с тем же идентификатором агента OpenTelemetry , что зарегистрировано в Foundry, и настройте azure monitor следующим образом:

from azure.monitor.opentelemetry import configure_azure_monitor
from agent_framework.observability import create_resource, enable_instrumentation

configure_azure_monitor(
    connection_string="InstrumentationKey=...",
    resource=create_resource(),
    enable_live_metrics=True,
)
# optional if you do not have ENABLE_INSTRUMENTATION in env vars
enable_instrumentation()

# Create your agent with the same OpenTelemetry agent ID as registered in Foundry
agent = Agent(
    client=...,
    name="My Agent",
    instructions="You are a helpful assistant.",
    id="<OpenTelemetry agent ID>"
)
# use the agent as normal

Панель мониторинга Aspire

Для локальной разработки без настройки Azure можно использовать панель мониторинга Aspire Dashboard, которая выполняется локально через Docker и обеспечивает отличный интерфейс просмотра телеметрии.

Настройка панели мониторинга Aspire с помощью Docker

# Pull and run the Aspire Dashboard container
docker run --rm -it -d \
    -p 18888:18888 \
    -p 4317:18889 \
    --name aspire-dashboard \
    mcr.microsoft.com/dotnet/aspire-dashboard:latest

Эта команда запустит панель мониторинга с помощью следующих команд:

  • Веб-интерфейс: доступно в http://localhost:18888
  • Конечная точка OTLP: доступна http://localhost:4317 для приложений для отправки данных телеметрии

Настройка приложения

Задайте следующие переменные среды:

ENABLE_INSTRUMENTATION=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Или включите их в .env файл и убедитесь, что вы вызываете load_dotenv() в начале приложения (Agent Framework не загружает .env файлы автоматически).

После завершения работы примера перейдите http://localhost:18888 в веб-браузер, чтобы просмотреть данные телеметрии. Следуйте руководству по просмотру панели мониторинга Aspire , чтобы пройти проверку подлинности на панели мониторинга и начать изучение трассировок, журналов и метрик.

Диапазоны и метрики

Когда все будет настроено, вы начнете видеть диапазоны и метрики, создаваемые автоматически для вас, диапазоны:

  • invoke_agent <agent_name>: это диапазон верхнего уровня для каждого вызова агента, он будет содержать все остальные диапазоны как дочерние.
  • chat <model_name>: этот диапазон создается при вызове базовой модели чата, он будет содержать запрос и ответ в качестве атрибутов, если enable_sensitive_data задано значение True.
  • execute_tool <function_name>: этот диапазон создается при вызове средства функции, он будет содержать аргументы функции и результат в виде атрибутов, если enable_sensitive_data задано значение True.

Созданные метрики:

  • Для клиента чата и chat операций:

    • gen_ai.client.operation.duration (гистограмма): эта метрика измеряет длительность каждой операции в секундах.
    • gen_ai.client.token.usage (гистограмма): эта метрика измеряет использование маркеров в количестве маркеров.

  • Для вызова функции во время операций execute_tool :

    • agent_framework.function.invocation.duration (гистограмма): эта метрика измеряет длительность каждого выполнения функции в секундах.

Пример выходных данных трассировки

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

{
    "name": "invoke_agent Joker",
    "context": {
        "trace_id": "0xf2258b51421fe9cf4c0bd428c87b1ae4",
        "span_id": "0x2cad6fc139dcf01d",
        "trace_state": "[]"
    },
    "kind": "SpanKind.CLIENT",
    "parent_id": null,
    "start_time": "2025-09-25T11:00:48.663688Z",
    "end_time": "2025-09-25T11:00:57.271389Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.operation.name": "invoke_agent",
        "gen_ai.provider.name": "openai",
        "gen_ai.agent.id": "Joker",
        "gen_ai.agent.name": "Joker",
        "gen_ai.request.instructions": "You are good at telling jokes.",
        "gen_ai.response.id": "chatcmpl-CH6fgKwMRGDtGNO3H88gA3AG2o7c5",
        "gen_ai.usage.input_tokens": 26,
        "gen_ai.usage.output_tokens": 29
    }
}

Эта трассировка показывает:

  • Идентификаторы трассировки и диапазона: для сопоставления связанных операций
  • Сведения о времени: при запуске и завершении операции
  • Метаданные агента: идентификатор агента, имя и инструкции
  • Сведения о модели: используемый поставщик ИИ (OpenAI) и идентификатор ответа
  • Использование маркеров: количество входных и выходных маркеров для отслеживания затрат

Samples

В репозитории есть несколько примеров microsoft/agent-framework , демонстрирующих эти возможности. Дополнительные сведения см. в папке примеров наблюдаемости. Эта папка содержит примеры для использования телеметрии нулевого кода, а также.

Полный пример

# Copyright (c) Microsoft. All rights reserved.

import asyncio
from random import randint
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.observability import configure_otel_providers, get_tracer
from agent_framework.openai import OpenAIChatClient
from opentelemetry.trace import SpanKind
from opentelemetry.trace.span import format_trace_id
from pydantic import Field

"""
This sample shows how you can observe an agent in Agent Framework by using the
same observability setup function.
"""


# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/02-agents/tools/function_tool_with_approval.py and samples/02-agents/tools/function_tool_with_approval_and_sessions.py.
@tool(approval_mode="never_require")
async def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    await asyncio.sleep(randint(0, 10) / 10.0)  # Simulate a network call
    conditions = ["sunny", "cloudy", "rainy", "stormy"]
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."


async def main():
    # calling `configure_otel_providers` will *enable* tracing and create the necessary tracing, logging
    # and metrics providers based on environment variables.
    # See the .env.example file for the available configuration options.
    configure_otel_providers()

    questions = ["What's the weather in Amsterdam?", "and in Paris, and which is better?", "Why is the sky blue?"]

    with get_tracer().start_as_current_span("Scenario: Agent Chat", kind=SpanKind.CLIENT) as current_span:
        print(f"Trace ID: {format_trace_id(current_span.get_span_context().trace_id)}")

        agent = Agent(
            client=OpenAIChatClient(),
            tools=get_weather,
            name="WeatherAgent",
            instructions="You are a weather assistant.",
            id="weather-agent",
        )
        thread = agent.create_session()
        for question in questions:
            print(f"\nUser: {question}")
            print(f"{agent.name}: ", end="")
            async for update in agent.run(
                question,
                session=thread,
                stream=True,
            ):
                if update.text:
                    print(update.text, end="")


if __name__ == "__main__":
    asyncio.run(main())

Наблюдаемость с помощью OpenTelemetry

Платформа агента Go включает ПО промежуточного слоя OpenTelemetry, которое автоматически отслеживает вызовы агента.

Setup

import (
    "github.com/microsoft/agent-framework-go/provider/otelprovider"

    "go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    otellib "go.opentelemetry.io/otel"
)

// Create a tracer provider with a console exporter
exporter, _ := stdouttrace.New(stdouttrace.WithPrettyPrint())
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
defer tp.Shutdown(context.Background())
otellib.SetTracerProvider(tp)

Добавление ПО промежуточного слоя в агент

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
        Middlewares: []agent.Middleware{
            otelprovider.NewMiddleware(otelprovider.MiddlewareConfig{}), // OpenTelemetry tracing
        },
    },
})

ПО промежуточного слоя выдает диапазоны с атрибутами, включая:

  • gen_ai.provider.name — имя поставщика (например, openai)
  • gen_ai.agent.id — уникальный идентификатор агента
  • gen_ai.agent.name — отображаемое имя агента
  • gen_ai.agent.description — описание агента

Tip

См. полный пример, чтобы увидеть полностью рабочий пример.

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

Для обычного агента добавьте OpenTelemetry в конвейер чат-клиента или агента с UseOpenTelemetry или WithOpenTelemetry, как показано ранее. По умолчанию добавляет HarnessAgent инструментирование чат-клиента и агента OpenTelemetry:

using Microsoft.Agents.AI;
using OpenTelemetry;
using OpenTelemetry.Trace;

const string SourceName = "MyApplication.Harness";

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource(SourceName)
    .AddOtlpExporter()
    .Build();

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    OpenTelemetrySourceName = SourceName,
});

OpenTelemetrySourceName по умолчанию использует Experimental.Microsoft.Agents.AI. Имя, переданного в AddSource него, должно соответствовать. Установите для DisableOpenTelemetry = true того, чтобы опустить оба слоя инструментирования, добавленных в Использование.

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

Данные телеметрии содержат метаданные по умолчанию. Настройка OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true также записывает запросы, ответы, аргументы инструментов и результаты инструментов; включите его только в том случае, если политика экспорта и хранения подходит для данных.

HarnessAgent доступен из Microsoft.Agents.AI.Harness пакета.

Обычные Agent экземпляры уже включают уровень телеметрии; настройте поставщиков и экспортеров OpenTelemetry или configure_otel_providers() собственную настройку пакета SDK OpenTelemetry. create_harness_agent использует ту же глобальную конфигурацию и назначает имя поставщика, относящегося к использованию.

from agent_framework import create_harness_agent
from agent_framework.observability import configure_otel_providers

configure_otel_providers()

agent = create_harness_agent(
    client=client,
    otel_provider_name="my.application.harness",
)

otel_provider_name управляет именем поставщика, записанным в телеметрии Harness. По умолчанию он не настраивает microsoft.agent_framework.harnessназначение экспортера или телеметрии. Инструментирование включено по умолчанию, запись конфиденциальных данных отключена по умолчанию, и экспортер не установлен или настроен автоматически.

Поставщики OpenTelemetry — это ресурсы на уровне процесса. Настройте их один раз, защитите учетные данные и конечные точки экспортера, а также выполните очистку или закройте их в соответствии с выбранным пакетом SDK OpenTelemetry и экспортером. Установка ENABLE_INSTRUMENTATION=false или вызов disable_instrumentation() при отключении телеметрии. Включение ENABLE_SENSITIVE_DATA добавления необработанных сообщений, аргументов инструментов и результатов инструментов.

create_harness_agent выпущен в agent-framework-core.

В настоящее время упакованный Go Harness недоступен. Настройте ПО промежуточного слоя OpenTelemetry непосредственно на простом агенте Go, как показано ранее.

Дальнейшие действия

Навыки агента

  • Last updated on