Конфигурация трассировки для фреймворков агентов искусственного интеллекта (предварительный обзор)

Когда агенты ИИ ведут себя неожиданно в рабочей среде, трассировка позволяет быстро определить первопричину. Трассировка записывает подробные данные телеметрии, включая вызовы 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 откройте ресурс Application Insights, подключенный к проекту Foundry.

2. Выберите управление доступом (IAM).

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

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

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

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

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

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

Настройка трассировки для фреймворка агента Microsoft

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

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

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

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

• Microsoft Рабочие процессы агентной платформы — наблюдаемость

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

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

• Семантические соглашения OpenTelemetry для создания искусственного интеллекта
• пакет langchain-azure-ai в PyPI

Пример: агент 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-адрес конечной точки OpenAI Azure.
• AZURE_OPENAI_CHAT_DEPLOYMENT: имя развертывания модели чата.
• AZURE_OPENAI_VERSION: версия API, например 2024-08-01-preview.
• Пакет SDK обрабатывает учетные данные Azure с помощью DefaultAzureCredential, который поддерживает переменные среды, управляемое удостоверение и вход в VS Code.

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

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

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 версии 1. Определение инструментов и запроса

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.

Убедитесь в точности трассировок LangChain версии 1.0

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

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

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

Пример: агент LangGraph для отслеживания с помощью искусственного интеллекта Azure

В этом примере показан простой агент 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-адрес конечной точки OpenAI Azure.
• 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, выберите 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.

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

Устранение распространенных проблем

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

• Изучите основные понятия и архитектуру в обзоре трассировки агента.
• Если вы еще не включили трассировку, см. раздел Настройка трассировки в Microsoft Foundry.
• Визуализируйте метрики работоспособности и производительности агента с помощью панели мониторинга агента.
• Изучите более широкие возможности обозримости в области генерирующего ИИ.