watsonx Orchestrateを活用したLangfuseによる、AIエージェントの可観測性の強化

By Jobit Varughese

構築されるAIエージェントの数が日々増加する中、企業は意思決定や業務ワークフローをサポートするための自律型システムを検討しています。同時に、組織は、特に推論を大規模言語モデル（LLM）に依存するマルチエージェント・システムにおける、説明責任、ガバナンス、および本番環境への対応可能性について懸念を表明することがよくあります。明確な説明なしに応答を提供したり、一貫性のない動作を示したりするエージェントをビジネス環境で使用することは課題です。

これらの課題は、カスタムのオーケストレーション・コードを必要とせずに、セルフホスティング、ツールベースの推論、API呼び出し、およびエンタープライズ・グレードの制御をサポートする、構造化されたプラットフォームを提供するIBM® watsonx Orchestrateを使用することで解決できます。

Dynamiq社は、大手保険会社のお客様向けにマルチエージェント法務リサーチ・アシスタントを構築し、より複雑なリサーチ・エージェントにエスカレーションする前に、低コストのIBM Granite分類器を介してクエリーをルーティングしました。この極めて重要なワークフローを実用化するには、すべての推論ステップとツール呼び出しに対する深い可視性が必要でした。IBM watsonx Orchestrateを統合することで、Dynamiq社はすべての意思決定が完全に追跡、監査、および引用可能であることを保証し、ガバナンスを犠牲にすることなく契約レビュー時間を90分から45分に短縮しました。

このチュートリアルでは、watsonx Orchestrate Agent Development Kit（ADK）を使用して、watsonx Orchestrate内にAIエージェントを作成する方法を学びます。LangChainまたはLangGraphベースのAIシステムでは、開発者は再試行、状態管理、および非同期実行を手動で処理することが頻繁にあります。watsonx Orchestrate ADKは、一貫したエンタープライズ対応のエージェント・デプロイメントを可能にする統合されたライフサイクル管理により、このプロセスを容易にします。

Pythonを使用して、リスク評価ロジックの作成、エージェントの動作の定義、および実際の実行トレースによってエージェントの動作を監視および強化するためのLangfuseの組み込みを行います。このチュートリアルは、GitHubでも見つけることができます。

Langfuseとは

Langfuseは、LLMアプリケーションおよびエージェントを監視するための、OpenTelemetryをベースに構築されたオープンソースのLLMオブザーバビリティー・プラットフォームです。リクエストごとおよびセッションごとのレベルで、LLM呼び出し、ツール呼び出し、トークン使用量、メタデータ、およびレイテンシーを含むエージェント実行のトレースを監視するために、テレメトリー（トレース、メトリクス、およびログ）を使用します。

これにより、開発者は、エージェントが実世界のシナリオでどのように機能するかについての深い洞察を獲得し、不正確な出力の根本原因を特定し、より高い信頼性と効率性のためにエージェントの動作を体系的に最適化できるようになります。

ユースケース概要：ベンダーリスクインテリジェンス

このチュートリアルのゴールは、確実性のあるルールベースの分析を通じてベンダー・リスクを評価する、エンタープライズ・ガバナンス用のAIエージェントを構築することです。私たちは、財務格付け、セキュリティ認証、およびインシデント履歴を持つベンダーの合成データ・セットを作成しました。エージェントはこのデータを処理し、その意思決定の正当な理由を提供しながら、ベンダーを特定のリスク層（低、中、または高）に分類します。

また、ユーザーがベンダーを比較したり、データポイントの変更がリスク・スコアにどのように影響するかをシミュレートしたりできる対話型のフォローアップもサポートしており、企業コンプライアンスに必要な高度な監査可能性を保証します。

以下は、このチュートリアルで構築した完成済みのベンダー・リスク・エージェントのガイド付きデモです。開始する前に構築するものの明確なイメージを持てるよう、エージェントがベンダーを分類し、質問に応答し、Langfuseを通じてその推論をトレースする方法をご覧ください。

ハンズオン・デモ

前提条件

このチュートリアルを完了するには、以下が必要です。

システムにPython 3.11以降がインストールされていること。
watsonx Orchestrateアカウント。このチュートリアルでは、試用版アカウントで十分です。アカウントをお持ちでない場合は、IBM Cloudを使用して30日間の無料トライアルを作成できます。
Orchestrateユーザー・インターフェース（UI）からのwatsonx Orchestrate APIキー。
システムにwatsonx Orchestrate ADKがインストールされていること。

手順

ステップ1：watsonx Orchestrateにサインイン

IBM Cloudを通じてwatsonx Orchestrateにサインインし、watsonx Orchestrate UIを開きます。プロファイル・メニューから「設定」を開いた後、「APIの詳細」に移動します。新しいAPIキーを作成し、コピーして安全に保存します。ローカル開発中、watsonx Orchestrate ADKはこのAPIキーで認証されます。watsonx Orchestrateは、エージェント・ロジックを構築およびテストするためのローカルのSDK（Software Development Kit）のように機能します。

ステップ2：ローカル開発環境を整える

このステップでは、ローカル開発環境を作成します。このチュートリアルを通じて、Powershell内のADKによって提供されるorchestratedコマンドライン・インターフェース（CLI）を介して、ローカル開発サーバーの実行、ツールのインポート、環境のセットアップ、およびエージェントの作成を行います。プロジェクトを構築するディレクトリーに移動することから始めます。次に、新しいPython仮想環境を作成します。

python -m venv .venv

隔離されたPython環境が.venvフォルダー内に作成されます。仮想環境を使用することで、このチュートリアルのすべての依存関係がシステム全体のPythonインストールから分離されます。

次に、仮想環境を有効化します。オペレーティング・システムによって、使用する有効化コマンドが決まります。

Windowsの場合：

.\.venv\Scripts\activate

macOSおよびLinux：

source ./.venv/bin/activate

有効化されると、端末プロンプトの先頭に.venv が表示され、仮想環境内で作業していることが示されます。

ステップ3：watsonx Orchestrate ADKをインストールする

仮想環境が有効な状態で、ローカル・マシンにwatsonx Orchestrate ADKをインストールします。ADKを使用するには、既存のwatsonx Orchestrate環境に接続します。PowerShellで以下のコマンドを実行します。

pip install --upgrade ibm-watsonx-orchestrate

公式インストール・ドキュメントの手順に従って、ADKインストールの次のステップに進むことができます。

注: このチュートリアルでは、watsonx Orchestrate Developer Editionランタイムをローカルで実行し、認証情報を使用してwatsonx Orchestrate SaaSインスタンスに接続します。

この方法を実行するには、プロジェクト・フォルダーのルートに.envというファイルを作成し、以下の値を追加します。

WO_DEVELOPER_EDITION_SOURCE=orchestrate

WO_INSTANCE=<your_watsonx_orchestrate_instance_url>

WO_API_KEY=<your_watsonx_orchestrate_api_key>

この.envファイルはサーバーを実行するために必要です。次のステップでは、orchestrate server start -e .env -l.コマンドで起動します。

ステップ4：ADK内でwatsonx Orchestrate環境を設定する

次に、ローカル環境をwatsonx Orchestrateに接続するために、有効なwatsonx Orchestrate APIキーをADKに設定する必要があります。

注: watsonx Orchestrate ADKは、IBM Cloud、AWS、オンプレミス・デプロイメントを含む、複数の環境タイプと互換性があります。このチュートリアルでは、オンプレミス環境を使用し、ADK CLIを介してAPIキーで認証します。ADKは内部で認証情報を安全に管理するため、このセットアップで環境変数を手動で構成する必要はありません。

プロジェクト・ディレクトリーから（仮想環境を有効化した状態で）、以下のコマンドを実行してwatsonx Orchestrate環境を追加します。

orchestrate env add -n onprem-env -u <service-instance-url>

ここで、service-instance-urlはお客様のwatsonx OrchestrateインスタンスのURLです。この情報は、watsonx Orchestrate UIの「設定」にある同じ「APIの詳細」タブで見つけることができます。

次に、追加した環境を有効化します。

orchestrate env activate onprem-env

プロンプトが表示されたら、ステップ1で取得したwatsonx Orchestrateキーを入力します。環境が有効化されると、エージェントやツールのインポート、サーバーの実行など、ADKに関連するそれ以降のすべてのコマンドがwatsonx Orchestrate環境で実行されます。

注: Developer Editionを使用してすべてをローカルで実行する場合は、以下を介してデフォルトのローカル環境を有効化できます。

orchestrate env activate local

これにより、ADKが組み込みのローカルOrchestrate環境に切り替わり、ローカル・テストに役立ちます。

ステップ5：ローカルのwatsonx Orchestrateプロジェクトを初期化する

このステップでは、Vendor Risk Intelligence Agentの定義、ツール、およびソースコードを含むエージェント・フレームワーク・テンプレートを作成します。次に、ローカルのADKベースの開発に必要なフォルダー構造を作成します。

── adk-project(vendor-risk-intel)/
── agents/
── tools/
── src/

エージェントの構造を作成するために、ここに提供されているコマンドを追加できます。

mkdir -p adk-project\(vendor-risk-intel\)/{agents,src,tools}

各フォルダーには特定の目的があります。

「agents」フォルダーには、エージェント・モデルの指示、推論ルール、および構成が含まれるYAMLファイルが含まれています。これにより、システムがユーザーの質問にどのように答えるかが決まります。「tools」フォルダーには、エージェントに提供されるツールを記述したYAMLファイルが保持されます。「src」フォルダーには、カスタム・ツールおよびビジネス・ロジック用のPython実装が含まれています。

ステップ6：watsonx Orchestrateサーバーを起動します

ツールやエージェントをインポートする前に、インポートされたものを受信して保存できるように、watsonx Orchestrateサーバーを起動します。プロジェクト・フォルダーのルートから、以下のコマンドを実行します。

orchestrate server start -e .env -l

ステップ7：Langfuseのオブザーバビリティー（SaaS）を設定する

次のステップは、どのツールが呼び出されたか、レイテンシー、エラーの発生場所など、ランタイムのエージェントの動作を分析するエージェントのオブザーバビリティーです。この目的のために、watsonx Orchestrate ADK環境でLangfuseのオブザーバビリティーを有効化します。

このチュートリアルでは、LangfuseのSaaSバージョンが使用されているため、ローカルでLangfuseを実行することなくトレースをキャプチャできます。

Langfuseを構成する前に、watsonx Orchestrateサーバーが実行されていること（ステップ6）を確認してください。

次に、langfuse.comでLangfuseアカウントを作成します。サインイン後、新しい組織とプロジェクトを作成します。プロジェクト設定から、プロジェクトID、パブリック・キー、シークレット・キー、およびホストURLをコピーします。

このセクションの後に示されているコマンドを使用して、watsonx Orchestrate ADKでLangfuseを設定し、プレースホルダーをコピーした値に置き換えます。

orchestrate settings observability langfuse configure `
    --url “<LANGFUSE_HOSTNAME>/api/public/otel” `
    --api-key “<LANGFUSE_SECRET_KEY>“ `
    --health-uri “https://cloud.langfuse.com” `
    --config-json “{\”public_key\”:\”<LANGFUSE_PUBLIC_KEY>\”}” `
    --project-id “<LANGFUSE_PROJECT_ID>“

このコマンドが正常に終了すると、Langfuseモジュールがwatsonx Orchestrate環境に完全に統合されます。この段階では、エージェントとのすべてのやり取りがLangfuseモジュールに自動的に記録されます。

サーバーが実行されたので、エージェントをテストできます。

ステップ 8：ベンダー・リスク・インテリジェンス・エージェントを定義する

次のステップは、Vendor Risk Intelligence Agentを定義することです。watsonx Orchestrate ADKのエージェントは、エージェントのゴール、推論の制限、モデル構成、および許可されたツールを記述したYAMLファイルで宣言されます。

「agents」ディレクトリー内に、「vendor-risk-agent.yaml」という名前のファイルを作成します。このファイルは、自由形式の推論とは異なり、すべての回答が確実性のある推論に基づくことを保証する、エージェントのプロンプト管理レイヤーです。

このチュートリアルで使用されるエージェント定義を次に示します。以下のエージェント定義を「agents/vendor-risk-agent.yaml」ファイルにコピーして貼り付けます。その後、ファイルを保存します。

spec_version: v1
kind: native
name: Vendor_Risk_Intelligence_Agent
description: Produces precise risk assessments using verified vendor profiles.
instructions: |
    You are a Vendor Risk Auditor.
    You MUST answer ALL questions by:
    1. Calling the Python tool `evaluate_all_vendor_risks`
    2. Reasoning strictly from the returned structured data
    3. Explaining answers using rules, signals, and outcomes from the tool
    4. Call evaluate_all_vendor_risks exactly once per question
    5. For definition questions, quote rules directly from the tool output
    NEVER infer meanings of financial ratings.
    NEVER guess intent.
    NEVER answer without tool evidence.
    Question handling rules:
    - Definition questions (e.g. “Does B+ mean High risk?”):
→ Explain the rule from the tool’s `rules` section.
    - Why questions (e.g. “Why is DataSecure Ltd High risk?”):
→ Cite strong and weak signals for that vendor.
    - Comparison questions (e.g. “Why is A Medium but B High?”):
→ Compare signal counts and types.
    - Policy questions (e.g. “What causes High risk?”):
→ Quote the tool’s rules exactly.
    - If the tool does not support a claim:
→ Say so explicitly.
    Use deterministic language only.
    Do not use speculative words like “might”, “could”, or “appears”.

llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
style: react
tools:
    - evaluate_all_vendor_risks

この構成により、エージェントは何、なぜ、どのように、および比較に関する質問に対して予測通りに動作するようになります。ツールの出力で明示的に定義されていない限り、財務格付けやリスクの意味についての想定を禁止することで、システムはハルシネーションを防止します。

ステップ 9：ベンダー・リスク評価ロジックを実装する

このステップでは、ベンダー・リスク・アセスメントを実行するPythonツールを実装します。watsonx Orchestrate ADKでは、エージェントが結果を取得するために起動するPythonツールを介して、カスタム・ビジネス・ロジックが実装されます。ドメイン固有の動作のためにモデルのファインチューニングに依存するのではなく、このチュートリアルでは、一貫した成果を保証するPythonツールを介して、確実性のあるルールベースの推論を実装する方法を実演します。

「src」フォルダー内に、「main.py」という名前のファイルを作成します。このファイルには、私たちが作成したベンダー・データ・セット、リスク評価ルール、およびエージェントにロジックを提供する「evaluate_all_vendor_risks」という名前のPythonツールが含まれています。

リスク・ロジックはルールベースです。高リスクの兆候に関しては、財務パフォーマンスの低さ、過去のセキュリティ・インシデント、または規制当局からの問い合わせを理由に、企業が高リスク・スコアを受け取る場合があります。認証の欠如、単一の運用インシデント、または気象条件による中断を理由に、企業が中リスク・スコアを受け取る場合があります。

「evaluate_all_vendor_risks」関数はwatsonx Orchestrateツールとして作成され、実行中にエージェントによって呼び出し可能になります。ツールは、分類の原因となった正確な理由とともに、最終的なリスク・レベルを含む構造化された出力を返します。

注: このチュートリアルに含まれているmain.pyファイルは、ベンダー・リスク評価ロジックの最終更新バージョンです。最初のコード・セットはエージェントの誤動作を引き起こしましたが、これはLangfuseのトレースを介して分析されました。Langfuseのトレースは、このチュートリアルの後半のステップにあるスクリーンショットで確認できます。

このチュートリアルで使用するmain.pyファイルの完全な実装を次に示します。それをsrc/main.pyにコピーして貼り付けます。その後、ファイルを保存します。

from ibm_watsonx_orchestrate.agent_builder.tools import tool

# =====================================================
# IN-MEMORY VENDOR DATA
# =====================================================

VENDORS = [
    {
        “name”: “CloudHostCo”,
        “financial_rating”: “A-“,
        “security_certifications”: [“ISO 27001”, “SOC2 Type II”],
        “past_incidents”: [{“type”: “Operational”, “year”: 2023}],
        “recent_news”: [“Minor service disruption in EU region”]
    },
    {
        “name”: “DataSecure Ltd”,
        “financial_rating”: “B”,
        “security_certifications”: [“SOC2 Type I”],
        “past_incidents”: [{“type”: “Security”, “year”: 2022}],
        “recent_news”: [“Suspicious login attempts on admin accounts”]
    },
    {
        “name”: “FinPay Solutions”,
        “financial_rating”: “A”,
        “security_certifications”: [“PCI-DSS”],
        “past_incidents”: [],
        “recent_news”: [“Regulatory inquiry about payment delays”]
    },
    {
        “name”: “GreenLogistics Corp”,
        “financial_rating”: “B+”,
        “security_certifications”: [“ISO 9001”],
        “past_incidents”: [{“type”: “Operational”, “year”: 2023}],
        “recent_news”: [“Weather-related disruptions in the UK”]
    }
]

REQUIRED_CERTS = {“ISO 27001”, “SOC2 Type II”, “PCI-DSS”}

# =====================================================
# RISK COMPUTATION (FIXED)
# =====================================================

def compute_vendor_risk(vendor: dict) -> dict:
    strong_signals = []
    weak_signals = []

  # ---------- Strong signals ----------

    # Financial risk ONLY for B or worse (NOT B+)
    if vendor[“financial_rating”] in {“B”, “B-“, “C”, “C-“, “D”}:
        strong_signals.append(“Weak financial rating”)

    # Security incident
    if any(i[“type”].lower() == “security” for i in vendor.get(“past_incidents”, [])):
        strong_signals.append(“Past security incident”)

    # Regulatory inquiry
    for news in vendor.get(“recent_news”, []):
        if “regulatory inquiry” in news.lower():
        strong_signals.append(“Regulatory inquiry”)
        break

    # ---------- Weak signals ----------

    # Missing key certifications
    certs = set(vendor.get(“security_certifications”, []))
    if not REQUIRED_CERTS.issubset(certs):
        weak_signals.append(“Missing key security certifications”)

    # Single operational incident
    incidents = vendor.get(“past_incidents”, [])
    if len(incidents) == 1 and incidents[0][“type”].lower() == “operational”:
        weak_signals.append(“Single operational incident”)

    # Weather-related disruptions are weak only
    for news in vendor.get(“recent_news”, []):
      if “weather” in news.lower():
        weak_signals.append(“Weather-related disruption”)
        break

    # ---------- Final decision ----------

    if len(strong_signals) >= 2:
        risk = “High”
    elif len(strong_signals) == 1 or len(weak_signals) >= 2:
        risk = “Medium”
    else:
        risk = “Low”

    return {
        “risk”: risk,
        “strong_signals”: strong_signals,
        “weak_signals”: weak_signals
    }

# =====================================================
# PYTHON TOOL
# =====================================================

@tool
def evaluate_all_vendor_risks() -> dict:
    “””
    Returns structured vendor risk assessments with explanations and rules.
    “””
    return {
        “rules”: {
            “financial_rating_rule”: “Only financial ratings of B or lower are treated as strong risk signals. B+ and above are not strong signals.”,
            “high_risk_rule”: “High risk requires two or more strong signals.”,
            “medium_risk_rule”: “Medium risk occurs with one strong signal or two or more weak signals.”,
            “weather_rule”: “Weather-related disruptions are always weak signals.”,
            “operational_rule”: “A single operational incident is a weak signal.”
        },
        “vendors”: {
            v[“name”]: {
                “financial_rating”: v[“financial_rating”],
                “risk”: compute_vendor_risk(v)[“risk”],
                “strong_signals”: compute_vendor_risk(v)[“strong_signals”],
                “weak_signals”: compute_vendor_risk(v)[“weak_signals”]
            }
            for v in VENDORS
        }
    }

ステップ 10：Pythonツールとエージェントをwatsonx Orchestrateにインポートする

このステップでは、ツールとエージェントをwatsonx Orchestrateで利用可能にする必要があります。このプロセスは、有効化されたADK環境にこれらのコンポーネントをインポートすることによって行われます。インポート・コマンドを実行する前に、プロジェクトのルート・フォルダー（「agents」、「src」、および「tools」ディレクトリーを含むフォルダーと同じ）の中にいることを確認してください。

まず、watsonx Orchestrateが実行可能な機能として登録できるように、Pythonツールをインポートします。プロジェクト・ディレクトリーのルートから、以下のコマンドを実行します。

orchestrate tools import --kind python --file src/main.py --package-root .

このコマンドは、Pythonコードをモジュールにパッケージ化し、「evaluate_all_vendor_risks」ツールを登録して、エージェントから呼び出せるようにします。

orchestrate agents import -f agents/vendor-risk-agent.yaml

その後、Vendor Risk Intelligence Agentがwatsonx Orchestrate環境内のPythonツールに完全に統合されます。

ステップ11：エージェントをLangfuseでテストし、その挙動を分析する

ローカルのwatsonx Orchestrateサーバーが実行され、エージェントのオブザーバビリティーが有効になった状態で、エージェントをテストし、その動作をリアルタイムで分析できるようになりました。

以下のコマンドを実行してチャット・インターフェースを起動します。

orchestrate chat start

次に、ブラウザーでwatsonx OrchestrateのチャットUIを開きます。エージェント・セレクターから「Vendor_Risk_Intelligence_Agent」を選択し、ベンダー・リスクに関連する質問を開始します。

エージェントが正しく応答していること（およびPythonツールを確実性をもって呼び出していること）を確認するために、テストに使用できるいくつかのサンプル質問を以下に示します。

B+は高リスクを意味しますか。
DataSecure Ltd社はどのようなリスクですか。
中リスクの基準は何ですか。
どのベンダーが最も低い財務格付けを持っていますか。
FinPay solutions社がセキュリティ・インシデントを経験した場合、そのリスク・レベルはどのように変化しますか。
どのベンダーが運用インシデントを経験していますか。

エージェントとやり取りする際、ブラウザーでLangfuseダッシュボードを開きます。各ユーザー・クエリーは新しいトレースを作成し、session_idとユーザーIDを含みます。これらのトレースは、エージェントの完全な実行パスを記録します。トレースを選択することで、以下を分析できます。

エージェントの完全な入力と出力
Pythonツールの呼び出し
ツールによって返される構造化データ
最終的な回答に到達するまでの推論プロセス
プロセス内の各ステップのレイテンシー
複数の質問に対するセッションベースの会話フロー

このオブザーバビリティーは、前提の誤り、不完全なルール、予期しないエージェントの動作などのボトルネックを指摘するパフォーマンス・メトリクスを分析するのに役立ちます。

ステップ12：Langfuseの洞察を用いてエージェントの挙動を洗練させる

エージェントをテストした後、Langfuseのトレースを使用して不正確な応答を特定します。Langfuseは、各ツールの呼び出し、推論ステップ、および応答のレイテンシーを表示するため、なぜ回答が生成されたのかを容易に理解できるようになります。

このユースケースでは、トレース分析により、エージェントが財務的な意味を推論したり、ルールベースの証拠を明示的に引用せず実証に応答したりしたときに、いくつかの不正確な回答が発生したことが明らかになりました。このアクションを変更するために、エージェントの指示と対応するPythonコードが修正され、必要なツールのアクションを伴う厳格なルールベースの思考に修正されました。

更新されたファイルを再インポートした後、エージェントが再度テストされました。新しいトレースにより、応答が構造化されたツールの出力にしっかりと基づいていること、説明が確実性のものであること、およびすべての記述的な質問に対する応答が正確であることが保証されます。

この観察と洗練のプロセスは、ユーザーからのフィードバックに基づいて、Langfuseがエージェントの安全で健全な開発をどのように支援するかを示しています。

ベンダー・リスク・エージェントと実稼働中のLangfuseトレースを探索するには、以下のガイド付きデモをご覧ください。

まとめ

このチュートリアルでは、エンタープライズ・グレードのエージェントの作成に向けて開発された、watsonx Orchestrateによる構造化された信頼できるAIエージェントの作成手順を説明しました。シンプルなルールベースのPythonロジック、明確なエージェントの指示、および再利用可能なツールの統合により、最小限のコードと最大限の透明性で、ベンダー・リスク・アセスメントのユースケースを実装しました。

Langfuseの追加により、エージェントの動作を検出し、推論に伴う問題を特定することが容易になり、推測に頼ることなく継続的に正確性を向上できるようになりました。このアプローチは、企業がエージェント・システムをエンドツーエンドで最適化し、複雑なワークフローを自動化し、完全な透明性を持ってAIシステムをデプロイするのを支援します。

さらに重要なことに、watsonx Orchestrate ADKとLangfuseを組み合わせることで、企業は、より強力なガバナンスとより明確な推論、および短縮された開発時間によって、複雑なエージェント型ワークフローやAIアプリケーションをより迅速に設計、デバッグ、および拡張できるようになります。