AI エージェント フレームワークのトレースを構成する (プレビュー)

運用環境で AI エージェントが予期せず動作する場合、トレースを使用すると、根本原因をすばやく特定するための可視性が提供されます。 トレースでは、LLM 呼び出し、ツール呼び出し、エージェントの決定フローなど、詳細なテレメトリがキャプチャされるため、問題をデバッグし、待機時間を監視し、要求全体のエージェントの動作を把握できます。

Microsoft Foundry は、最小限のコード変更を必要とする一般的なエージェント フレームワークのトレース統合を提供します。 この記事では、次の方法について説明します。

• Microsoft Agent Framework とセマンティック カーネルの自動トレースを構成する
• LangChain と LangGraph の Microsoft OpenTelemetry ディストリビューションを設定する
• OpenTelemetry を使用して OpenAI Agents SDK をインストルメント化する
• Foundry ポータルにトレースが表示されることを確認する
• トレースに関する一般的な問題のトラブルシューティング

Microsoft Foundry スキルは、フレームワークのインストルメンテーションを構成し、Foundry でトレースを検証するのに役立ちます。

前提 条件

• フォンドリー プロジェクト。 詳細については、「Foundry プロジェクトを作成する」を参照してください。
• Azure Monitor Application Insights リソースに接続されたトレース。 設定するには、「 Microsoft Foundry でトレースを設定する」を参照してください。
• トレース インジェストのための Application Insights リソースに対する共同作成者以上のロール。
• トレースを表示するための接続された Application Insights リソースへのアクセス。 ログ ベースのクエリの場合は、関連付けられているLog Analytics ワークスペースへのアクセスも必要になる場合があります。
• Python 3.10 以降 (この記事のすべてのコード サンプルに必要)。
• microsoft-opentelemetry パッケージ (LangChain と LangGraph のサンプルに必要)。
• LangChain または LangGraph を使用する場合は、pip がインストールされたPython環境です。

テレメトリを表示できることを確認する

トレース データを表示するには、アカウントが接続された Application Insights リソースにアクセスできることを確認します。

1. Azure ポータルで、Foundry プロジェクトに接続されている Application Insights リソースを開きます。

2. [アクセス制御 (IAM)] を選択します。

3. ユーザーまたはグループに適切なロールを割り当てます。

   ログ ベースのクエリを使用する場合は、まず、Log Analytics 閲覧者ロールを付与します。 基になるLog Analytics テーブルが保護されている場合は、特権監視データ閲覧者ロールも付与します。

セキュリティとプライバシー

トレースでは、機密情報 (ユーザー入力、モデル出力、ツールの引数と結果など) をキャプチャできます。

• 開発およびデバッグ中にコンテンツの記録を有効にして、要求と応答の完全なデータを表示します。 運用環境でコンテンツの記録を無効にして、機密データを保護します。 この記事のサンプルでは、コンテンツの記録は環境変数 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT、 OTEL_SEMCONV_STABILITY_OPT_IN、および AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACINGによって制御されます。
• シークレット、資格情報、またはトークンをプロンプトまたはツールの引数に格納しないでください。

詳細なガイダンスについては、 セキュリティとプライバシーに関するページを参照してください。

Microsoft Agent Framework とセマンティック カーネルのトレースを構成する

Microsoft Foundry には、Microsoft Agent Framework とセマンティック カーネルの両方とのネイティブ統合があります。 いずれかのフレームワークを使用して構築されたエージェントは、Foundry プロジェクトでトレースが有効になっているときにトレースを自動的に出力します。追加のコードやパッケージは必要ありません。

トレースが機能していることを確認するには:

1. エージェントを少なくとも 1 回実行します。
2. Foundry ポータルで、 Observability>Traces に移動します。
3. エージェントの各操作のスパンを含む新しいトレースが表示されていることを確認します。

トレースは通常、エージェントの実行後 2 ~ 5 分以内に表示されます。 高度な構成については、フレームワーク固有のドキュメントを参照してください。

• Microsoft Agent Framework ワークフロー – 可観測性
• セマンティック カーネルの可観測性

OpenInference インストルメンテーション ライブラリを使用してトレースを構成する

Microsoft Foundry では、AI エージェントをトレースするための OpenInference インストルメンテーション ライブラリがサポートされています。 これらの openinference-* パッケージは、さまざまなフレームワークに自動インストルメンテーションを提供し、ホストされるエージェント (Foundry にデプロイされたエージェント) と Foundry 以外のエージェント (Foundry の外部でホストされているエージェント) の両方をトレースするために使用できます。

PyPI で使用可能なインストルメンテーション パッケージを参照します。 LangChain については、Microsoft OpenTelemetry distro LangChain サンプルを参照してください。このサンプルでは、use_microsoft_opentelemetry を使用してAzure Monitorエクスポートと LangChain の自動インストルメンテーションを有効にする方法を示します。

重要な要件は、OpenInference トレースを特定のエージェントに関連付することです。 これを実現する方法は、エージェントの実行場所によって異なります。

ホスト型エージェント (Foundry にデプロイされた)

ホストされているエージェント サーバー パッケージのいずれかを使用して Foundry にエージェントをデプロイすると、トレースの関連付けは自動的に処理されます。 サーバー パッケージ:

• OpenTelemetry スパン用の Azure Monitor エクスポートを構成します。
• Foundry UI がクエリを実行して表示できるように、すべてのスパンをプロジェクト、エージェント名、エージェントのバージョン、およびエージェント ID 属性で強化します。

追加の構成は必要ありません。 フレームワークに関連する openinference-* インストルメンテーション パッケージをインストールすると、トレースが Foundry ポータルに自動的に表示されます。

Foundry の外部でホストされる Microsoft Agent Framework エージェント

Microsoft Agent Framework エージェントが Foundry ホスト型エージェント サーバー パッケージと共にデプロイされていない場合は、Microsoft OpenTelemetry ディストリビューションを使用Azure Monitorエクスポートとエージェント フレームワークのインストルメンテーションを構成します。 ディストリビューションでは、Azure Monitor エクスポーターを有効にして、エージェント ID 属性をスパンに追加できます。

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    azure_monitor_connection_string="...",
    sampling_ratio=1.0,
    enable_sensitive_data=True,
    instrumentation_options={
        "agent-framework": {
            "enabled": True,
            "agent_id": "ms-imagination-agent",
            "agent_name": "ms-imagination-agent",
        },
    },
)

azure_monitor_connection_stringを Foundry プロジェクトに接続されている Application Insights リソースに設定します。 開発中にプロンプトと完了のコンテンツをキャプチャするには、 enable_sensitive_data=True設定します。

Foundry の外部でホストされている LangChain エージェント

Foundry ホスト型エージェント サーバー パッケージを使用してエージェントがデプロイされていない場合は、Microsoft OpenTelemetry distro を使用してAzure Monitorエクスポートおよび LangChain インストルメンテーションを構成します。 ディストリビューションでは、Azure Monitor エクスポーターを有効にして、LangChain スパンにエージェント ID 属性を追加できます。

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "weather_info_agent_771929",
            "agent_name": "Weather information agent",
        },
    },
)

APPLICATIONINSIGHTS_CONNECTION_STRINGを Foundry プロジェクトに接続されている Application Insights リソースに設定します。 開発中にプロンプトと完了のコンテンツをキャプチャするには、 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT、 OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental、および AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=trueを設定します。

LangChain と LangGraph のトレースを構成する

Microsoft OpenTelemetry distro を使用して、LangChain および LangGraph 操作用の OpenTelemetry 準拠スパンを出力します。 これらのトレースは、Foundry ポータルの Observability>Traces ビューに表示されます。

• 生成 AI の OpenTelemetry セマンティック規則
• Microsoft OpenTelemetry distro LangChain サンプル

サンプル: Azure AI トレースを使用した LangChain v1 エージェント

このエンドツーエンドのサンプルを使用して、Microsoft OpenTelemetry ディストリビューションを使用して LangChain v1 (プレビュー) エージェントをインストルメント化します。 このディストリビューションでは、最新の OpenTelemetry (OTel) セマンティック規則を使用して LangChain の自動インストルメンテーションが可能になるため、Foundry 監視ビューで豊富なトレースを表示できます。

LangChain v1: パッケージをインストールする

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

LangChain v1: 環境を構成する

• APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Monitor Application Insightsのトレース用接続文字列。
• AZURE_OPENAI_ENDPOINT: Azure OpenAI エンドポイント URL。
• AZURE_OPENAI_CHAT_DEPLOYMENT: チャット モデルのデプロイ名。
• AZURE_OPENAI_VERSION: API のバージョン (例: 2024-08-01-preview)。
• SDK は、環境変数、マネージド ID、VS Code サインインをサポートする DefaultAzureCredential を使用して、Azure資格情報を解決します。

ローカル開発用の .env ファイルにこれらの値を格納します。

LangChain v1: Tracer のセットアップ

from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "weather_info_agent_771929",
            "agent_name": "Weather information agent",
        },
    },
)

LangChain v1: モデルのセットアップ (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://cognitiveservices.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 v1: エージェントを作成する

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 v1: トレースを使用してエージェントを実行する

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}}
    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()

Microsoft OpenTelemetry ディストリビューションを有効にすると、すべての LangChain v1 操作 (LLM 呼び出し、ツール呼び出し、エージェントステップ) によって、最新のセマンティック規則を使用して OpenTelemetry スパンが出力されます。 これらのトレースは Foundry ポータルの Observability>Traces ビューに表示され、Application Insights リソースにリンクされます。

LangChain v1 トレースを確認する

エージェントの実行後:

1. トレースが伝達されるまで 2 ~ 5 分待ちます。
2. Foundry ポータルで、 Observability>Traces に移動します。
3. 指定した名前のトレース ("Weather information agent" など) を探します。
4. トレースを展開して、LLM 呼び出し、ツール呼び出し、およびエージェントステップのスパンを表示します。

トレースが表示されない場合は、「 一般的な問題のトラブルシューティング 」セクションを確認してください。

サンプル: Azure AI トレースを使用する LangGraph エージェント

このサンプルでは、Microsoft OpenTelemetry ディストリビューションでインストルメント化された単純な LangGraph エージェントを示し、グラフ ステップ、ツール呼び出し、およびモデル呼び出しに対して OpenTelemetry に準拠したトレースを出力します。

LangGraph: パッケージをインストールする

pip install \
  microsoft-opentelemetry \
  "langgraph>=1.0.0" \
  "langchain>=1.0.0" \
  langchain-openai \
  azure-identity \
  python-dotenv

LangGraph: 環境を構成する

• APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Monitor Application Insightsのトレース用接続文字列。
• AZURE_OPENAI_ENDPOINT: Azure OpenAI エンドポイント URL。
• AZURE_OPENAI_CHAT_DEPLOYMENT: チャット モデルのデプロイ名。
• AZURE_OPENAI_VERSION: API のバージョン (例: 2024-08-01-preview)。

ローカル開発用の .env ファイルにこれらの値を格納します。

LangGraph トレーサーのセットアップ

from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_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://cognitiveservices.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"}}
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()

Microsoft OpenTelemetry ディストリビューションを有効にすると、LangGraph の実行により、モデル呼び出し、ツール呼び出し、グラフ遷移に対して OpenTelemetry に準拠したスパンが出力されます。 これらのトレースは Application Insights に送られ、Foundry ポータルの [Observability>Traces ] ビューに表示されます。

LangGraph トレースを確認する

エージェントの実行後:

1. トレースが伝達されるまで 2 ~ 5 分待ちます。
2. Foundry ポータルで、 Observability>Traces に移動します。
3. 指定した名前のトレース ("Music Player Agent" など) を探します。
4. トレースを展開して、グラフ ノード、ツール呼び出し、モデル呼び出しのスパンを表示します。

トレースが表示されない場合は、「 一般的な問題のトラブルシューティング 」セクションを確認してください。

サンプル: Azure AI トレースを使用した LangChain 0.3 のセットアップ

この最小限のセットアップでは、Microsoft OpenTelemetry ディストリビューションと AzureChatOpenAI を使用して、LangChain 0.3 アプリケーションで Azure AI トレースを有効にする方法を示します。

LangChain 0.3: パッケージをインストールする

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  microsoft-opentelemetry \
  python-dotenv

LangChain 0.3: 環境を構成する

• APPLICATIONINSIGHTS_CONNECTION_STRING: トレースに使用する Application Insights の接続文字列。 この値を見つけるには、Azure ポータルで Application Insights リソースを開き、Overview を選択し、Connection String をコピーします。
• AZURE_OPENAI_ENDPOINT: Azure OpenAI エンドポイント URL。
• AZURE_OPENAI_CHAT_DEPLOYMENT: チャットモデルのデプロイ名。
• AZURE_OPENAI_VERSION: API のバージョン (例: 2024-08-01-preview)。
• AZURE_OPENAI_API_KEY: Azure OpenAI API キー。

LangChain 0.3: トレーサーとモデルのセットアップ

import os
from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Enable Azure Monitor export and LangChain auto-instrumentation
use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "trip_planner_orchestrator_v3",
            "agent_name": "Trip Planner Orchestrator",
        },
    },
)

# Model: Azure OpenAI
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,
)

ディストリビューションが初期化されると、LangChain 0.3 操作はグローバルに自動インストルメント化されます。 チェーンまたはエージェントを実行すると、2 ~ 5 分以内に Foundry ポータルの >] ビューにトレースが表示されます。

OpenAI Agents SDK のトレースを構成する

OpenAI Agents SDK では、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 にサインイン>。 新しいファウンドリーのトグルがオンになっていることを確認します。 これらの手順は Foundry (新規) を参照します。
2. プロジェクトに対してトレースが接続されていることを確認してください。 必要に応じて、Microsoft Foundry でトレースのセットアップを行います。
3. エージェントを少なくとも 1 回実行します。
4. Foundry ポータルで、 Observability>Traces に移動します。
5. エージェントの各操作のスパンを含む新しいトレースが表示されていることを確認します。

トレースは通常、エージェントの実行後 2 ~ 5 分以内に表示されます。 この時間が経過してもトレースが表示されない場合は、「 一般的な問題のトラブルシューティング」を参照してください。

一般的な問題のトラブルシューティング

関連するコンテンツ

• エージェント トレースの概要の主要な概念とアーキテクチャについて説明します。
• トレースをまだ有効にしていない場合は、「 Microsoft Foundryを参照してください。
• エージェント監視ダッシュボードを使用して 、エージェントの正常性とパフォーマンスのメトリックを視覚化します。
• 生成 AI の広範な可観測性の機能を探索します。