Поделиться через

Настройка трассировки для фреймворков агентов ИИ (предварительный просмотр)

Это важно

Элементы, обозначенные в этой статье как (предварительная версия), сейчас предлагаются в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и мы не рекомендуем ее для рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Дополнительные сведения см. в разделе Supplemental Terms of Use for Microsoft Azure Previews.

Замечание

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

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

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

  • Настройка автоматической трассировки для Microsoft Agent Framework
  • Настройка трассировщика langchain-azure-ai для LangChain и LangGraph
  • Инструментирование пакета SDK для агентов OpenAI с помощью OpenTelemetry
  • Убедитесь, что трассировки отображаются на портале Foundry
  • Устранение распространенных проблем трассировки

Предпосылки

  • Проект Foundry с трассировкой, подключенной к Azure Monitor Application Insights.
  • Участник или выше по ролям в ресурсе Application Insights для получения и обработки данных трассировки.
  • Доступ к ресурсу Application Insights, подключенному для просмотра отслеживания. Для запросов на основе журналов может также потребоваться доступ к связанной рабочей области Log Analytics.
  • Python 3.10 или более поздней версии (требуется для всех примеров кода в этой статье).
  • Пакет langchain-azure-ai версии 0.1.0 или более поздней (требуется для примеров LangChain и LangGraph).
  • Если вы используете LangChain или LangGraph, требуется среда Python с установленным pip.

Подтвердите, что вы можете просматривать телеметрию

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

  1. В Azure portal откройте ресурс Application Insights, подключенный к project Foundry.

  2. Выберите Access control (IAM).

  3. Назначьте соответствующую роль пользователю или группе.

    Если вы используете запросы на основе журналов, начните с предоставления роли чтения Log Analytics.

Безопасность и конфиденциальность

Трассировка может записывать конфиденциальную информацию (например, входные данные пользователя, выходные данные модели и аргументы и результаты инструментов).

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

Дополнительные рекомендации см. в разделе "Безопасность и конфиденциальность".

Замечание

Данные трассировки, хранящиеся в Application Insights, подчиняются настройкам хранения данных вашей рабочей области и модели тарификации Azure Monitor. Для управления затратами рекомендуется настроить частоту выборки или периоды хранения в рабочей среде. См. цены на Azure Monitor и настройку удержания данных и архивацию.

Настройка трассировки для Microsoft Agent Framework

Microsoft Foundry имеет собственные интеграции с Microsoft Agent Framework. Агенты, созданные с помощью любого фреймворка, автоматически генерируют трассировки, когда трассировка включена для проекта Foundry — дополнительный код или пакеты не требуются.

Чтобы проверить, работает ли трассировка:

  1. Запустите агент по крайней мере один раз.
  2. На портале Foundry перейдите к наблюдаемости>трассировки.
  3. Убедитесь, что новая трассировка отображается с диапазонами для операций агента.

Трассировки обычно отображаются в течение 2–5 минут после выполнения агента. Дополнительные сведения о конфигурации см. в документации для конкретной платформы:

Настройка трассировки для LangChain и LangGraph

Замечание

Интеграция трассировки для LangChain и LangGraph в настоящее время доступна только в Python.

Используйте пакет langchain-azure-ai для генерации спанов, совместимых с OpenTelemetry, для операций LangChain и LangGraph. Эти трассировки отображаются в представлении Наблюдаемость>Трассировки на портале Foundry.

Пример: агент-программа LangChain версии 1 с трассировкой Azure ИИ

Используйте этот комплексный пример для инструментирования агента LangChain версии 1 (предварительная версия) с помощью трассировщика langchain-azure-ai. Этот трассер реализует новейшие семантические соглашения OpenTelemetry (OTel), поэтому вы можете просматривать подробные трассировки в панели наблюдаемости Foundry.

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

pip install \
  langchain-azure-ai \
  langchain \
  langgraph \
  langchain-openai \
  azure-identity \
  python-dotenv \
  rich

LangChain версии 1. Настройка среды

  • APPLICATION_INSIGHTS_CONNECTION_STRING: строка подключения Azure Monitor Application Insights для отслеживания.
  • AZURE_OPENAI_ENDPOINT: URL-адрес конечной точки Azure OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: название развертывания модели чата.
  • AZURE_OPENAI_VERSION: версия API, например 2024-08-01-preview.
  • Этот пакет SDK разрешает учетные данные Azure, используя DefaultAzureCredential, который поддерживает переменные окружения, управляемую идентификацию и вход через VS Code.

Сохраните эти значения в .env файле для локальной разработки.

LangChain версии 1: настройка трассировки

from dotenv import load_dotenv
import os
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Weather information agent",
    id="weather_info_agent_771929",
)

tracers = [azure_tracer]

LangChain версии 1: настройка модели (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
)

LangChain v1: Определение инструментов и подсказки

from dataclasses import dataclass
from langchain_core.tools import tool

system_prompt = """You are an expert weather forecaster, who speaks in puns.

You have access to two tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location

If a user asks you for the weather, make sure you know the location.
If you can tell from the question that they mean wherever they are,
use the get_user_location tool to find their location."""

# Mock user locations keyed by user id (string)
USER_LOCATION = {
    "1": "Florida",
    "2": "SF",
}

@dataclass
class UserContext:
    user_id: str

@tool
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

LangChain v1: использование контекста среды выполнения и определение инструмента для сведений о пользователе

from langgraph.runtime import get_runtime
from langchain_core.runnables import RunnableConfig

@tool
def get_user_info(config: RunnableConfig) -> str:
    """Retrieve user information based on user ID."""
    runtime = get_runtime(UserContext)
    user_id = runtime.context.user_id
    return USER_LOCATION[user_id]

LangChain версии 1. Создание агента

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from dataclasses import dataclass

@dataclass
class WeatherResponse:
    conditions: str
    punny_response: str

checkpointer = InMemorySaver()

agent = create_agent(
    model=model,
    prompt=system_prompt,
    tools=[get_user_info, get_weather],
    response_format=WeatherResponse,
    checkpointer=checkpointer,
)

LangChain версии 1. Запуск агента с трассировкой

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
    context = UserContext(user_id="1")

    r1 = agent.invoke(
        {"messages": [{"role": "user", "content": "what is the weather outside?"}]},
        config=config,
        context=context,
    )
    print(r1.get("structured_response"))

    r2 = agent.invoke(
        {"messages": [{"role": "user", "content": "Thanks"}]},
        config=config,
        context=context,
    )
    print(r2.get("structured_response"))

if __name__ == "__main__":
    main()

С включенным параметром langchain-azure-ai все операции LangChain версии 1 (вызовы LLM, вызовы инструментов, действия агента) выдают диапазоны OpenTelemetry с использованием последних семантических соглашений. Эти трассировки отображаются в представлении Observability Traces> на портале Foundry и связаны с ресурсом Application Insights.

Подсказка

После запуска агента подождите несколько минут, пока будут отображаться трассировки. Если трассировки не отображаются, убедитесь, что строка подключения Application Insights указана правильно, и проверьте раздел Troubleshoot common issues.

Проверьте трассировки LangChain версии 1

После запуска агента:

  1. Подождите 2–5 минут для распространения трассировок.
  2. На портале Foundry перейдите к наблюдаемости>трассировки.
  3. Найдите трассировку с указанным именем (например, "Агент сведений о погоде").
  4. Разверните трассировку, чтобы просмотреть диапазоны вызовов LLM, вызовов инструментов и действий агента.

Если вы не видите следы, проверьте раздел «Устранение распространенных проблем».

Пример: агент LangGraph с трассировкой при помощи Azure AI

В этом примере показан простой агент LangGraph, использующий langchain-azure-ai для генерации трассировок, соответствующих OpenTelemetry, для шагов графа, вызовов инструментов и активации модели.

LangGraph: установка пакетов

pip install \
  langchain-azure-ai \
  langgraph>=1.0.0 \
  langchain>=1.0.0 \
  langchain-openai \
  azure-identity \
  python-dotenv

LangGraph: настройка среды

  • APPLICATION_INSIGHTS_CONNECTION_STRING: строка подключения Azure Monitor Application Insights для отслеживания.
  • AZURE_OPENAI_ENDPOINT: URL-адрес конечной точки Azure OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: название развертывания модели чата.
  • AZURE_OPENAI_VERSION: версия API, например 2024-08-01-preview.

Сохраните эти значения в .env файле для локальной разработки.

Настройка трассировщика LangGraph

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=os.getenv("OTEL_RECORD_CONTENT", "true").lower() == "true",
    name="Music Player Agent",
)

LangGraph: инструменты

from langchain_core.tools import tool

@tool
def play_song_on_spotify(song: str):
    """Play a song on Spotify"""
    # Integrate with Spotify API here.
    return f"Successfully played {song} on Spotify!"

@tool
def play_song_on_apple(song: str):
    """Play a song on Apple Music"""
    # Integrate with Apple Music API here.
    return f"Successfully played {song} on Apple Music!"

tools = [play_song_on_apple, play_song_on_spotify]

LangGraph: настройка модели (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
).bind_tools(tools, parallel_tool_calls=False)

Создание рабочего процесса LangGraph

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver

tool_node = ToolNode(tools)

def should_continue(state: MessagesState):
    messages = state["messages"]
    last_message = messages[-1]
    return "continue" if getattr(last_message, "tool_calls", None) else "end"

def call_model(state: MessagesState):
    messages = state["messages"]
    response = model.invoke(messages)
    return {"messages": [response]}

workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)

workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "action",
        "end": END,
    },
)
workflow.add_edge("action", "agent")

memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

LangGraph: запуск с помощью трассировки

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
input_message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

for event in app.stream({"messages": [input_message]}, config, stream_mode="values"):
    event["messages"][-1].pretty_print()

При включении langchain-azure-ai выполнение LangGraph выдает диапазоны, совместимые с OpenTelemetry, для вызовов моделей, вызовов инструментов и переходов графов. Эти трассировки будут передаваться в Application Insights и отображаться в представлении наблюдаемости>трассировки на портале Foundry.

Подсказка

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

Проверьте трассировки LangGraph

После запуска агента:

  1. Подождите 2–5 минут для распространения трассировок.
  2. На портале Foundry перейдите к наблюдаемости>трассировки.
  3. Найдите след с указанным именем (например, "Агент музыкального проигрывателя").
  4. Разверните трассировку, чтобы просмотреть диапазоны для узлов графа, вызовов инструментов и вызовов модели.

Если вы не видите следы, проверьте раздел «Устранение распространенных проблем».

Пример: настройка LangChain 0.3 с помощью отслеживания Azure AI

** Эта минимальная настройка показывает, как включить трассировку ИИ Azure в приложении LangChain 0.3, используя трассировщики langchain-azure-ai и AzureChatOpenAI.

LangChain 0.3: установка пакетов

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  langchain-azure-ai \
  python-dotenv

LangChain 0.3: настройка среды

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Строка подключения для Application Insights для трассировки. Чтобы найти это значение, откройте ресурс Application Insights в Azure portal, выберите Overview и скопируйте Connection String.
  • AZURE_OPENAI_ENDPOINT: URL-адрес конечной точки OpenAI Azure.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: имя развертывания модели чата.
  • AZURE_OPENAI_VERSION: версия API, например 2024-08-01-preview.
  • AZURE_OPENAI_API_KEY: Ключ API Azure OpenAI.

Замечание

В этом примере для простоты используется проверка подлинности ключа API. Для производственных нагрузок используйте DefaultAzureCredential вместе с get_bearer_token_provider, как показано в примерах LangChain v1 и LangGraph.

LangChain 0.3: трассировка и настройка модели

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Tracer: emits spans conforming to updated OTel spec
azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Trip Planner Orchestrator",
    id="trip_planner_orchestrator_v3",
)
tracers = [azure_tracer]

# Model: Azure OpenAI with callbacks for tracing
llm = AzureChatOpenAI(
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    temperature=0.2,
    callbacks=tracers,
)

Присоедините callbacks=[azure_tracer] к вашим цепочкам, инструментам или агентам для отслеживания операций LangChain 0.3. После запуска цепочки или агента трассировки появляются в представлении наблюдаемости>трассировок на портале Foundry через 2–5 минут.

Настройка трассировки для пакета SDK для агентов OpenAI

Пакет SDK для агентов OpenAI поддерживает инструментирование OpenTelemetry. Используйте следующий фрагмент кода, чтобы настроить диапазоны трассировки и экспорта для Azure Monitor. Если APPLICATION_INSIGHTS_CONNECTION_STRING этот параметр не задан, экспортер возвращается в консоль для локальной отладки.

Перед запуском примера установите необходимые пакеты:

pip install opentelemetry-sdk opentelemetry-instrumentation-openai-agents azure-monitor-opentelemetry-exporter

import os
from opentelemetry import trace
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

# Configure tracer provider + exporter
resource = Resource.create({
    "service.name": os.getenv("OTEL_SERVICE_NAME", "openai-agents-app"),
})
provider = TracerProvider(resource=resource)

conn = os.getenv("APPLICATION_INSIGHTS_CONNECTION_STRING")
if conn:
    from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
    provider.add_span_processor(
        BatchSpanProcessor(AzureMonitorTraceExporter.from_connection_string(conn))
    )
else:
    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

trace.set_tracer_provider(provider)

# Instrument the OpenAI Agents SDK
OpenAIAgentsInstrumentor().instrument(tracer_provider=trace.get_tracer_provider())

# Example: create a session span around your agent run
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent_session[openai.agents]"):
    # ... run your agent here
    pass

Проверка трассировок на портале Foundry

  1. Войдите в Microsoft Foundry. Убедитесь, что переключатель New Foundry включен. Эти действия относятся к Foundry (new).
  2. Убедитесь, что ваш проект подключён к трассировке. При необходимости следуйте настройке трассировки в Microsoft Foundry.
  3. Запустите агент по крайней мере один раз.
  4. На портале Foundry перейдите к наблюдаемости>трассировки.
  5. Убедитесь, что новая трассировка отображается с диапазонами для операций агента.

Трассировки обычно отображаются в течение 2–5 минут после выполнения агента. Если следы по-прежнему не появляются по истечении этого времени, см. Устранение распространенных проблем.

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

Проблема Причина Резолюция
Вы не видите следов в Foundry. Отслеживание не подключено, нет недавнего трафика или задержана сбор данных. Подтвердите подключение Application Insights, создайте новый трафик и обновите его через 2–5 минут.
Вы не видите диапазоны LangChain или LangGraph Обратные вызовы трассировки не присоединены к процессу Убедитесь, что передаете трассировщик в callbacks (например, config = {"callbacks": [azure_tracer]}) для того выполнения, которое вы хотите отследить.
Диапазоны LangChain отображаются, но вызовы инструментов отсутствуют Инструменты не привязаны к модели, или узел инструмента не настроен. Убедитесь, что средства передаются bind_tools() в модель, а узлы инструментов добавляются в граф.
Трассировки отображаются, но являются неполными или отсутствующими диапазонами Запись содержимого отключена или некоторые операции не инструментируются Включите полную телеметрию через enable_content_recording=True. Для пользовательских операций добавьте диапазоны вручную с помощью пакета SDK OpenTelemetry.
При запросе телеметрии возникают ошибки авторизации Отсутствуют разрешения RBAC в Application Insights или Log Analytics Подтвердите доступ в Сontrol доступа (IAM) для подключенных ресурсов. Для запросов журнала назначьте роль читателя Log Analytics.
Конфиденциальное содержимое отображается в трассировках Запись содержимого включена, а запросы, аргументы инструментов или выходные данные включают конфиденциальные данные Отключите запись содержимого в рабочей среде и удалите конфиденциальные данные перед их передачей в телеметрию.

Дальнейшие шаги

  • Last updated on