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

Important

この記事で "(プレビュー)" と付記されている項目は、現在、パブリックプレビュー段階です。このプレビューはサービスレベルアグリーメントなしで提供されており、運用環境ではお勧めしません。特定の機能はサポート対象ではなく、機能が制限されることがあります。詳細については、「 Microsoft Azure プレビューの使用条件を参照してください。

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

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

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

[前提条件]

Application Insights に接続されたトレース機能を持つFoundryプロジェクト。
トレースインジェストのための Application Insights リソースに対する共同作成者以上のロール。
トレースを表示するために、接続されている Application Insights リソースにAccessします。ログベースのクエリの場合は、関連付けられている Log Analytics ワークスペースへのaccessが必要な場合もあります。
Python 3.10 以降 (この記事のすべてのコードサンプルに必要)。
langchain-azure-ai パッケージバージョン 0.1.0 以降 (LangChain と LangGraph のサンプルに必要)。
LangChain または LangGraph を使用する場合は、pip がインストールされた Python 環境。

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

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

Azure portalで、Foundry projectに接続されている Application Insights リソースを開きます。
Access control (IAM) を選択します。
ユーザーまたはグループに適切なロールを割り当てます。

ログベースのクエリを使用する場合は、まず Log Analytics 閲覧者ロールを付与します。

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

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

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

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

注

Application Insights に格納されているトレースデータは、ワークスペースのデータ保持設定と Azure Monitor の価格に従います。コスト管理の場合は、運用環境でサンプリングレートまたは保持期間を調整することを検討してください。 Azure Monitor の価格とデータの保持とアーカイブの構成を参照してください。

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

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

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

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

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

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

注

LangChain と LangGraph のトレース統合は、現在 Python でのみ使用できます。

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

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

このエンドツーエンドのサンプルを使用して、langchain-azure-ai トレーサーを使用して LangChain v1 (プレビュー) エージェントをインストルメント化します。このトレーサーは、最新の OpenTelemetry (OTel) セマンティック規則を実装しているため、Foundry 監視ビューで豊富なトレースを表示できます。

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

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

LangChain v1: 環境を構成する

APPLICATION_INSIGHTS_CONNECTION_STRING: トレース用の Application Insights connection stringをAzure監視します。
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
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 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"}, "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 v1 操作 (LLM 呼び出し、ツール呼び出し、エージェントステップ) が、最新のセマンティック規則を使用して OpenTelemetry スパンを出力します。これらのトレースは Foundry ポータルの Observability>Traces ビューに表示され、Application Insights リソースにリンクされます。

ヒント

エージェントを実行した後、トレースが表示されるまで数分待ちます。トレースが表示されない場合は、Application Insights connection stringが正しいことを確認し、一般的な問題セクションを確認します。

LangChain v1 トレースを確認する

エージェントを実行した後で:

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

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

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

このサンプルでは、langchain-azure-ai を使用してインストルメント化された単純な LangGraph エージェントを示し、グラフステップ、ツール呼び出し、モデル呼び出しに対して 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: トレース用の Application Insights connection stringをAzure監視します。
AZURE_OPENAI_ENDPOINT: Azure OpenAI エンドポイント URL。
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://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"}, "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 ポータルの [Observability>Traces ] ビューに表示されます。

ヒント

グラフノードとエッジ遷移ごとに個別のスパンが作成されるため、エージェントの意思決定フローを簡単に視覚化できます。

LangGraph トレースを確認する

エージェントを実行した後で:

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

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

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

この最小限のセットアップでは、langchain-azure-ai トレーサーと AzureChatOpenAI を使用して、LangChain 0.3 アプリケーションで Azure AI トレースを有効にする方法を示します。

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 コネクションストリング。この値を見つけるには、Azure portalで 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 キー

注

このサンプルでは、わかりやすくするために API キー認証を使用します。運用ワークロードの場合は、LangChain v1 と LangGraph のサンプルに示すように、DefaultAzureCredentialでget_bearer_token_providerを使用します。

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 操作がトレースされるようにします。チェーンまたはエージェントを実行すると、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 ポータルでトレースを確認する

Microsoft Foundry にサインインします。 「新しいファウンドリー」トグルがオンになっていることを確認します。 これらの手順は Foundry (新規) を参照します。
プロジェクトのトレースが接続されていることを確認してください。必要に応じて、 Microsoft Foundry でのトレースの設定に関する記事を参照してください。
エージェントを少なくとも 1 回実行します。
Foundry ポータルで、 Observability>Traces に移動します。
エージェントの各操作のスパンを含む新しいトレースが表示されていることを確認します。

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

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

問題点	原因	解決策
Foundry にトレースが表示されない	トレースが接続されていない、最近のトラフィックがない、またはインジェストが遅れている	Application Insights 接続を確認し、新しいトラフィックを生成し、2 ~ 5 分後に更新します。
LangChain または LangGraph のスパンを見ることができない	トレースコールバックが実行にアタッチされていません	トレースする実行に対して、トレーサーを `callbacks` (たとえば、`config = {"callbacks": [azure_tracer]}`) で渡していることを確認します。
LangChain スパンが表示されるが、ツール呼び出しが見つからない	ツールがモデルにバインドされていないか、ツールノードが構成されていない	ツールがモデルの `bind_tools()` に渡され、ツールノードがグラフに追加されていることを確認します。
トレースは表示されるが、不完全または欠落しているスパンがある	コンテンツの記録が無効になっているか、一部の操作がインストルメント化されていない	完全なテレメトリの `enable_content_recording=True` を有効にします。カスタム操作の場合は、OpenTelemetry SDK を使用して手動スパンを追加します。
テレメトリのクエリを実行すると、承認エラーが表示される	Application Insights または Log Analytics に対する RBAC アクセス許可がありません	接続されているリソースの Access control (IAM) でaccessを確認します。ログクエリの場合は、Log Analytics 閲覧者ロールを割り当てます。
機密性の高いコンテンツがトレースに表示される	コンテンツの記録が有効になり、プロンプト、ツールの引数、または出力に機密データが含まれる	運用環境でのコンテンツの記録を無効にし、テレメトリに入る前に機密データを編集します。

次のステップ

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-11