AgentOps：watsonx Orchestrateを使用したIBM TelemetryによるAIエージェントの監視およびガバナンス

AIエージェントがより高度化し自律的になるにつれて、信頼性とガバナンスを確保するために、それらの振る舞い、パフォーマンス、および意思決定プロセスを理解することが不可欠になります。本番環境のAIエージェントを監視、観察、および管理するプラクティスであるAgentOpsは、信頼できるエージェント型AIシステムを構築するために必要な可視性を提供します。

このチュートリアルでは、AIエージェントを監視および統治するために、watsonx Orchestrate Developer EditionでIBM Telemetryをセットアップして使用するためのステップバイステップ・ガイドを提供します。個々のLLM呼び出しから完全なマルチステップ・ワークフローにいたるまで、AIエージェントのオブザーバビリティーを有効にして、その振る舞いを詳細に分析する方法を学習します。

このチュートリアルの終わりまでに、以下を行うことができるようになります：

• watsonx Developer Editionのローカルへのインストールと構成
• 包括的なエージェントのオブザーバビリティーのためのIBM Telemetryの有効化
• 外部ツールを統合した、事前構成済みAIエージェントのインポートとテスト
• 詳細なトレース、タスク、スパン、およびワークフローを通じたエージェントの振る舞いの分析
• 高度なアナリティクスを使用した、問題のデバッグとエージェント・パフォーマンスの最適化

IBM Telemetryは、AIエージェントがどのようにリクエストを実行するかに関する詳細な情報をキャプチャーする、watsonx Orchestrateのネイティブなオブザーバビリティー・フレームワークです。これは、ルーティングの決定やプロンプトの構築から、LLMの呼び出しやツールの呼び出しにいたるまで、エージェント・ライフサイクルのあらゆるステップを記録し、エージェントの振る舞いに対する完全な可視性を提供します。

IBM Telemetryを使用すると、パフォーマンス・メトリックスの追跡、LLMコストの監視、エラーの特定を行うことができ、エージェントが意図したとおりに動作していることを確実に確認できます。IBM Telemetryは、本番環境や大規模なAIシステム向けに設計された、エンタープライズ・グレードのオブザーバビリティーを提供します。

開始する前に、次の前提条件がご使用のシステムにインストールされ、構成されていることを確認してください：

• Python 3.8+（python --version で確認）
• 最低16 GBのRAM
• watsonx Orchestrate ADKを介したwatsonx Orchestrate Developer Edition

このガイドには、ADKのインストール・ステップが含まれています。

• watsonx Orchestrateのアカウントアカウントをお持ちでない場合は、30日間の無料トライアルが利用可能です。
• watsonx OrchestrateのAPIキーIBM® Cloudダッシュボードから生成

認証ステップは、このガイドの後半で説明します。

開始するには、HTTPS URLとしてhttps://github.com/IBM/ibmdotcom-tutorials.git を使用して、GitHubリポジトリーを複製します。リポジトリーを複製する方法の正確な手順については、 GitHubのドキュメンテーションを参照してください。

お好みの統合開発環境（IDE）（例えば、 Visual Studio Code ）でリポジトリーを開き、このチュートリアルのプロジェクト・フォルダーであるwxo-agentops を探します。このディレクトリーは、手順に沿って進める際に作業を行う場所です。

IBM watsonx Orchestrate Agent Development Kit（ADK）は、watsonx Orchestrate Developer Editionのインストール、構成、および管理を単純にするCLIツールです。

ADKを使用するには、既存のwatsonx Orchestrate環境に接続する必要があります。watsonx Orchestrateのアカウントをまだお持ちでない場合は、30日間の無料トライアルに登録することができます。すでにアカウントをお持ちの場合は、それを使用してADKに必要な環境認証情報を提供できます。

これらのステップでは、依存関係を隔離しておくために推奨されるアプローチである、Python仮想環境を使用したインストールについて案内します。代替のインストール方法および詳細な手順については、「Getting started with the ADK」の文書を参照してください。

プロジェクト・ディレクトリーに新しいPython仮想環境を作成します：

このステップでは、隔離されたPython環境を含む.venv フォルダが作成されます。

有効化コマンドは、ご使用のオペレーティング・システムによって異なります。

macOSおよびLinux

Windows

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

仮想環境が有効化された状態で、pipを使用してADKをインストールします：

このコマンドは、ADKとそのすべての依存関係をダウンロードしてインストールします。インストールの完了には数分かかる場合があります。

注:以前のバージョンのADK（ 2.0 ）がインストールされている場合は（> 2.0 ）、pip install --upgrade ibm-watsonx-orchestrate を実行してください。ステップ4bのトラブルシューティング・ステップを実行しなければならない場合もあります。

ADKは.envファイルを使用してユーザーの認証情報を認証し、watsonx Orchestrate Developer Editionを設定します。必要な環境変数は、選択した認証方法によって異なります。このチュートリアルでは、最も簡単に開始できるwatsonx Orchestrateアカウント・メソッドを使用しています。

代替の認証方法および詳細な構成手順については、環境ファイルの構成に関する文書を参照してください。

wxo-agentops ディレクトリ内に.envを作成します。 提供されたテンプレートをコピーしてファイルを作成します。

テキスト・エディターで.envファイルを開き、次の2つの重要なフィールドを設定します。

• WO_INSTANCE ：このURLは、使用しているwatsonx Orchestrateインスタンスです。この情報は、watsonx Orchestrateアカウントにログインし、インスタンスの詳細に移動することで確認できます。プロファイル・アイコン ＞「設定」の順にクリックし、「API詳細」タブを選択します。APIの使用開始に関する詳細な手順については、watsonx Orchestrateのドキュメンテーションを参照してください。

URLは次の形式に従います：

サービス・インスタンスURLをコピー・アンド・ペーストして、.envファイルのテンプレート値を置き換えます。リージョン（例えば、us-south）は地理的位置によって異なります。

• WO_API_KEY ：このキーは、IBMクラウド・サービスへの接続を認証するwatsonx Orchestrateアプリケーション・プログラミング・インターフェース（API）キーです。このキーは、IBM Cloudアカウントのダッシュボードから生成または取得できます。<your-api-key>を実際のAPIキーに置き換えます。APIキーを生成するためのステップバイステップの手順については、ドキュメンテーションをご覧ください。

API キーは安全に保管し、決してバージョン管理にコミットしないでください。.env ファイルは誤って露出を防ぐためにすでに.gitignore に含めておくべきです。

これで、マシン上でwatsonx Orchestrateサーバーのローカル・インスタンスを実行する、watsonx Orchestrate Developer Editionをインストールする準備が整いました。このステップではIBM Telemetryも有効になり、オブザーバビリティー機能にすぐにアクセスできるようになります。

インストール・コマンドの理解

ADKは、インストール・プロセス全体を処理する単一のコマンドを提供します：

このコマンドの機能を分解して説明します：

• orchestrate server start ：watsonx Orchestrate Developer Editionサーバーを初期化して起動します
• -e <path-.env-file> ：認証情報を含む構成ファイルを指します
• --with-ibm-telemetry ：IBM Telemetryのネイティブなオブザーバビリティー・フレームワークを有効にします

nbspwxo-agentopsnbspディレクトリーからコマンドを実行します：

次のコマンドは、サーバー環境を初期化して、watsonx Orchestrate Developer Editionサーバーを起動します：orchestrate server start -e <path-.env-file> 。--with-ibm-telemetry フラグを追加すると、そのネイティブなオブザーバビリティー・フレームワークであるIBM Telemetryが有効になります。

IBM Telemetryを備えたwatsonx Orchestrateサーバーをインストールするには、このコマンドを実行します：

このコマンドは、以下を対象としてADKによって管理される内部コンテナーを作成します：

• watsonx Orchestrateサーバー
• PostgreSQLおよびRedisデータベース
• IBM Telemetryサービス
• 必要な依存関係

ADKは、これらのコンテナがhttp://localhost:3000 上で相互に通信できるように、仮想ネットワークを自動的に構成します。

インストール・プロセスには数分かかる場合があり、特に初回実行時は必要なイメージがダウンロードされるため時間がかかります。インストールが成功すると、この例と同様の出力が生成されます：

このメッセージが表示されたら、セットアップは完了です。IBM Telemetryを備えたローカルのwatsonx Orchestrate環境が実行されました。

インストールの失敗やハングアップが発生した場合は、次の手順を実行します。

1.サーバーのリセット：

このコマンドは、watsonx Orchestrate用に作成されたすべてのコンテナを停止して削除し、初期状態に戻します。

2.インストールの再開：

リセット後、起動コマンドを再度実行します。

3.サーバー・ログのコンテナ・ステータスの確認：

Orchestrateサーバーのサービス・ログを表示して、警告やエラーを確認できます。

上記の手順が機能しない場合は、サーバーをリセットし、サーバー環境を完全に削除して（orchestrate server purge）、再インストールします。

watsonx Orchestrateサーバーのインストールが成功したため、ローカル環境をアクティベートし、AIエージェントと対話するためのチャット・インターフェースを起動する必要があります。

watsonx Orchestrate ADKは、複数の環境（ローカル、開発、本番など）をサポートしています。作成したローカル環境を明示的に有効化する必要があります。

環境がアクティブであるという確認メッセージが表示されます。

これにより、以降のすべてのADKコマンドのデフォルトのコンテキストとしてローカル環境が設定されます。使用するすべてのエージェント、ツール、または構成は、このローカル・インスタンスをターゲットにするようになります。

次のコマンドを使用して、watsonx OrchestrateチャットUIサービスを起動します。

このコマンドは、Webベースのチャット・インターフェースを初期化し、デフォルトのブラウザーで自動的に開きます。次のような出力が表示されます。

チャット・インターフェースを使用すると、AIエージェントと簡単に対話できます。ブラウザーが自動的に開かない場合は、手動で以下に移動できます。http://localhost:3000/chat-lite.

チャット・インターフェースがロードされると、対話の準備が整った新しいチャット・ウィンドウが表示されます。この段階では、エージェントをまだインポートしていないため、インターフェース内はほとんど空の状態です。これは予期されている結果であり、次のステップで最初のエージェントを追加します。

環境のセットアップが完了したため、IBM Telemetryの監視機能を示す、事前構成されたAIエージェントをインポートします。この気象エージェントは、外部のAPIツールを使用してリアルタイムの気象データを取得し、観察や分析のための実用的な例を提供します。

気象エージェントは、以下の理由から理想的な出発点となります。

• ツールの使用例の提示：エージェントが外部APIを呼び出す方法を示します
• 明確で観察可能な振る舞いの提供：各リクエストは予測可能なパターンに従います
• 有意義なテレメトリー・データの生成：IBM Telemetryで分析可能な豊富なトレースを生成します
• エラー・シナリオの包含：テレメトリーが障害をどのように処理するかを理解するのに役立ちます
• 自動化の例示：エージェントの行動を通じて手動によるデータ検索を排除します

プロジェクトのルート(wxo-agentops )からWeather Agentフォルダに移動します:

このディレクトリーには、2つのYAML構成ファイルが含まれています。

• get_weather.yaml ：気象APIツールを定義します
• weather_agent.yaml ：このツールを使用するエージェントを定義します

ツールは、エージェントが特定のアクションを実行するために呼び出すことができる、再利用可能な機能です。最初にget_weatherツールをインポートします。

次に、 --kind openapi フラグは、このツールがそのインターフェースを定義するためにOpenAPI仕様を使用していることを示します。ツールが正常にインポートされたという確認が表示されるはずです。

次に、このツールを使用するエージェントをインポートします。

このコマンドは、ローカルのwatsonx Orchestrate環境にWeather Agentを登録します。エージェントは以下で事前構成されています。

• 気象データを解釈する方法に関する指示
• get_weather ツールの呼び出し権限
• 無効なロケーションに対するフォールバックの振る舞い

チャット・インターフェースが実行されているブラウザーに戻ります。新しくインポートされたエージェントを表示するには、ページをリフレッシュする必要がある場合があります。

エージェントのドロップダウン・メニュー（通常はチャット・インターフェースの上部にあります）をクリックし、リストからWeather_Agentを選択します

Weather Agentを選択した状態で、テレメトリー・データを生成するためにいくつかの質問をしてみてください。

クエリーの例：

• 「ニューヨーク市の天気はどうですか。」
• 「ロンドンの現在の気温を教えてください。」
• 「東京の天気は何ですか。」
• 「今、シアトルでは雨が降っていますか。」

エージェントは、以下の手順で各リクエストを処理します：

1. クエリーの理解
2. 位置情報の抽出
3. 適切な座標を使用したget_weather ツールの呼び出し
4. 気象データの解釈
5. 自然言語での応答

Weather Agentとのすべての対話は、IBM Telemetryによってキャプチャーされています。システムは以下を記録しています：

• 完全な会話コンテキスト
• すべてのLLM呼び出しと使用されたトークン
• ツール呼び出しとその入力および出力
• ルーティングの決定とワークフロー・ステップ
• 実行時間と性能メトリクス
• 発生したエラーまたは例外
• 外部プロバイダーとの対話とその応答時間

次のステップでは、エージェントがどのように振る舞うかを正確に理解するために、このテレメトリー・データの詳細はこちら。

ここからが、このチュートリアルの最も強力な部分です。IBM Telemetryを使用して、エージェントの振る舞いに対する深い可視性を獲得します。IBM Telemetryは、エージェントがリクエストを処理する方法のあらゆる側面を理解できるようにする、複数のビューとアナリティクス・ツールを提供します。

ブラウザーを開き、https://localhost:8765/?serviceName=wxo-serverに移動します。インターフェースは、分析のために過去のエージェントの対話を再確認できるセッション再生を提供します。

注：URLはhttpsを使用していますが、このスペースはローカル開発環境であるため、ブラウザーに自己署名証明書に関するセキュリティー警告が表示される場合があります。このメッセージは予期されているものであり、ローカル環境でそのまま進めても安全です。

ログイン画面が表示されたら、ローカル・セッションを識別するための任意の名前を入力し、「ログイン」をクリックします。

メインのIBM Telemetryダッシュボードに移動します。

ダッシュボードには最近のトレースのリストが表示され、それぞれがエージェントとの単一のユーザー対話を表しています。「トレースとグループの選択」パネルの最初のトレースをクリックして、Weather Agentとの最新のチャットに関する詳細なアナリティクスを表示します。

このステップにより、エージェントの振る舞いを理解するためのセントラル・ハブとして機能する「エージェント・アナリティクス」画面に移動します。

エージェント・アナリティクス画面には、以下を含む選択されたトレースの概要が表示されます：

• 統計情報の要約：総実行時間、トークン使用量、コスト見積もり、およびベンチマーク・データ
• エージェント情報：どのエージェントがリクエストを処理したか
• ユーザー・クエリー：送信された元の質問
• 応答プレビュー：エージェントの最終回答
• ステータス・インジケーター：成功、警告、またはエラー

このハイレベルなビューにより、エージェントが期待通りに動作したか、またどれほど効率的に動作したかについての洞察を即座に得ることができます。

「タスク」セクションは、エージェントの振る舞いを分析するために最も多くの時間を費やす場所です。リクエスト中にエージェントが行ったすべてのこと（すべてのLLM呼び出し、ツール呼び出し、ルーティングの決定、および出力生成）の、視覚的でステップバイステップのタイムラインを提供します。

タスクは、エージェントが実際にワークフローを実行した方法を反映するように階層的に編成されているため、一連の操作とその関係性を簡単に理解できます。

watsonx Orchestrateエージェント・リクエストの標準的な実行パスを調べてみましょう。Weather Agentのトレースには、この例と同様の構造が表示されます。

このワークフローは、単一のユーザー・クエリーの完全なライフサイクルを示しています。各タスクが表す内容は次のとおりです：

• 0:_ROOT ：すべての子タスクを含むトップレベルのスパンです。このフォルダーは、エージェント実行の全体を保持するものと考えてください。リクエストがシステムに入ってから最終応答が配信されるまでの、完全なトレースの開始時間と終了時間を定義します。

ルート・タスクの期間によってユーザーが経験した総レイテンシーがわかるため、このアプローチは重要です。数値が高すぎる場合は、その子タスクを分析してボトルネックを特定できます。

• 0.0:agent_style_router ：ルーティング・タスクは、どのエージェントがメッセージを処理すべきかを決定し、リクエストを処理スタイルに分類します。ルーターは、受信したリクエストを分析し、それが対話型処理、ツール駆動型実行、検索拡張生成（RAG）、またはマルチエージェント・オーケストレーションを必要とするかどうかを判断します。

ルーターは、正しい下流のロジックが呼び出されることを確実にします。リクエストが誤ってルーティングされている場合は、ここで問題を特定します。

• 0.1:agent ：リクエスト全体をオーケストレーションする、主要なエージェント実行コンテキストです。このタスクは、システムとの対話、会話履歴、およびツールの応答からプロンプトを組み立てます。オーケストレーションのルールとポリシーを適用し、LLMへの入力を準備します。このタスクは、どのようなタイプのLLM呼び出しを行うかを決定します。

このステップは、オーケストレーションの「インテリジェンス」が発生する場所です。エージェント・タスクは、LLMが情報に基づいた意思決定を行うために必要なすべてのコンテキストを確実に受け取るようにします。

• 0.1.0:WatsonxChatModel.chat ：LLMへの実際の呼び出しであり、完全なプロンプトを受け取り、ツールを呼び出すか、説明を求めるか、または直接の回答を生成するかを決定します。テキストまたは構造化されたツール呼び出しのいずれかで応答を生成します。

このステップは、モデルが情報を処理して意思決定を行う「思考」のステップです。トークン使用量、レイテンシー、および品質の問題はすべて、このタスクに起因します。エージェントの動作が遅い、またはコストが高い場合、通常はこのステップが主な原因となります。

• 0.2:answer ：チェーンの最終ステップであり、LLMの出力を受け取り、配信のためにフォーマットします。このタスクは、LLMの未加工の出力を最終的な回答形式に変換し、後処理やフォーマットのルールを適用します。最後に、チャット・インターフェースに応答を配信します。

このタスクは、ユーザーが適切にフォーマットされた応答を確実に受け取るようにします。回答が途切れているか、不適切にフォーマットされている場合は、このステップで調査します。

タスク・ワークフローの要約

完全なワークフローを要約すると以下のとおり

1. ルーターによるリクエストの処理方法の決定
2. エージェントによるコンテキストとオーケストレーション・ロジックの準備
3. LLMによる応答またはツール呼び出しの生成
4. 回答のフォーマットと最終出力の返却

このワークフローのすべては、ROOTリクエスト・コンテナにラップされており、最初から最後までのエージェント実行の全体像を把握することができます。このレベルのオブザーバビリティーは、エージェントの運用や複雑なパイプラインを大規模に管理するMLOpsおよびDevOpsチームにとって不可欠です。

階層内の各タスクには、そのタスクが消費および生成したものに関する詳細なメタデータを提供する3つの属性カテゴリーが含まれています。

1. 入力属性：メッセージ、ツールの応答、システムへの指示、内部状態など、タスクが実行前に受信したすべての情報を表示します。

例：WatsonxChatModel.chat タスクでは、入力属性に、システム指示、会話履歴、および解釈が必要なツール結果を含んで完全に組み立てられたプロンプトが含まれます。

2. 出力属性：LLMの補完、ツールの呼び出し、決定など、タスクが生成したものを表示します。

例:同じ WatsonxChatModel.chat タスクは、自然言語の応答、またはget_weather(latitude=40, longitude=-74) のような構造化されたツール呼び出しのいずれかを出力する場合があります。

3. 一般属性：トークン使用量、タイミング情報、固有IDなどの識別子、モデル情報といったテレメトリー・メタデータを提供します。

例：タスクが450個の入力トークンと120個の出力トークンを使用し、実行に1.2秒かかり、ibm/granite-3.1-8b-instruct model を使ったことがあるかもしれません。

タスク属性の使用方法

これらの属性を組み合わせることで、モデルが何を認識し、何を決定し、どのように応答したかを完全に理解できます。

このレベルの詳細な情報は、デバッグ、最適化、および検証において非常に価値があります。

すべてのタスクには、そのタスクがどのように実行されたかを要約する、パフォーマンスおよびコスト関連のメトリクスが含まれています。これらのメトリクスは、エージェントのパフォーマンスに関する定量的なデータを提供します。

主要なメトリクスは以下のとおりです：

• 総実行時間：タスクの開始から終了までに要した時間
• LLM呼び出し回数：言語モデルが呼び出された回数
• ツール呼び出し回数：外部ツールが呼び出された回数
• トークン使用量：入力トークン、出力トークン、および消費された総トークン
• コスト見積もり：トークン使用量に基づく概算コスト（料金体系データが利用可能な場合）
• サブタスクの分散：子タスク間で作業がどのように分散されたか

これらのメトリクスは、パフォーマンスの最適化やエージェントの振る舞いのデバッグに役立ちます。また、並列化やキャッシュが可能な、処理の遅いタスクを特定するのにも役立ちます。このビューは、スケーリングに必要なリソース要件を理解し、経費を抑えるためにトークン使用量を追跡できるため、キャパシティー・プランニングに不可欠です。

例えば、トレースに8秒かかったものの、LLM呼び出しに費やされたのはわずか0.5秒であることに気づいた場合、ボトルネックは別の場所（おそらくツールの実行やネットワーク・レイテンシー）にあることがわかります。

タスクはエージェントの論理的なワークフローを示すのに対し、スパンは実行中に発生する基盤となるシステム・レベルの操作を表します。「スパン」タブをクリックすると、プラットフォームが各リクエストを処理するために内部で何を行っているかが明らかになります。

スパンは、オーケストレーション・フレームワーク（この場合はwxo-server内で実行されるオープンソース・フレームワークであるLangGraph）によって記録された下位レベルの実行ステップに対する可視性を提供します。各スパンは、以下のような個別の操作を表します：

• リクエストを正しいエージェントにルーティングする（agent_style_router）
• エージェントを呼び出し、そのコンテキストを初期化する（agent.task ）
• テンプレートからプロンプトとコンテキストを構築する(ChatPromptTemplate.task )
• アセンブリプロンプトでLLMを呼び出す方法 (WatsonxChatModel.chat )
• ユーザーに成果を返す（answer.task ）

タスクはエージェント実行の論理的なステップ（エージェントが何を達成しようとしているか）を示すのに対し、スパンは技術的なステップ（システムがそれをどのように達成するか）を示します。この2つのビューにより、上位レベルの理解と下位レベルのデバッグ機能の両方が得られます。

例： 0.1:agent のような単一タスクには、データベース・クエリー、キャッシュ検索、構成のロードを表す複数のスパンが含まれる場合があります。これらの操作は、エージェントの実行をサポートするためにバックグラウンドで実行されます。

各スパンには、追加のメタデータとコンテキストを提供するタグが含まれています。これらのタグは、エージェントのパフォーマンスのフィルタリング、デバッグ、および分析に不可欠です。

一般的なスパン・タグには以下が含まれます：

• エージェントの識別：agent_id 、agent_name
• セッション追跡：thread_id 、session_id 、conversation_id
• ワークフロー・コンテキスト：step_number 、workflow_path 、parent_span_id
• パフォーマンス・データ：token_count 、duration_ms 、model_name
• リクエストの詳細：tool_calls 、 input_preview 、output_preview

スパンは、レイテンシーの追跡、どの内部コンポーネントが失敗したかを確認することによる障害の理解、トレンドを特定するためのタグによるスパンのフィルタリングによるパターンの分析、およびセッションIDを使用した複数のトレース間にわたるスパンのリンクによる相互参照に役立ちます。

例えば、エージェントが時々ハングアップする場合、期間ごとにスパンをフィルタリングして、データベース・クエリーや外部サービスへのネットワーク呼び出しなど、どの内部操作に予想外の時間がかかっているかを特定できます。

「ワークフロー」タブは、エージェント・ワークフローの完全な実行構造を示す、「Runnablesツリー」と呼ばれる階層的な可視化を提供します。このビューは、複雑なマルチエージェント・システムやネストされた実行パターンを理解するのに特に役立ちます。

watsonx Orchestrateフレームワークにおいて、runnableとは、実行可能な作業またはタスクの単位です。Runnablesとは：

• 単純な操作：単一のLLM呼び出しまたはツール呼び出し
• 複合ワークフロー：チェーンのように結合された複数のrunnable
• 条件分岐：条件に基づく異なる実行パス
• 並列実行：同時に実行される複数のrunnable

Runnableツリーは親子関係を表示し、以下を簡単に確認できるようにします：

• どのタスクが他のタスクをトリガーするか：実行チェーンの追従
• 並列実行と順次実行の比較：ワークフローの同時実行性の理解
• 分岐ロジック：決定がどのように異なる実行パスにつながるか
• ワークフローの深さ：エージェント・ロジックのネストがどれほど深いか

Weather Agentのような単純なエージェントの場合、ワークフロー・ビューはタスク・ビューを忠実に反映します。ただし、以下を扱う場合、ワークフローは非常に価値のあるものになります：

• マルチエージェント・システム：1つのタスクで協調する複数の専門的なエージェント
• 複雑なオーケストレーション：異なるツールまたはサブエージェントの間で動的に選択を行うエージェント
• 反復的な洗練：条件が満たされるまでステップをループするエージェント
• 条件付きルーティング：中間結果に基づいて分岐するワークフロー
• スケーラブルなアーキテクチャー：現実世界の負荷を効率的に処理するワークフローの設計

例えば、クエリーにWeb検索が必要かどうかを最初に確認し、次に計算機ツールとデータベース・クエリー・ツールのどちらを使用するかを決定し、最後に結果を検証してから応答するエージェントを想定してください。Runnableツリーは、この分岐構造の全体を明確に示します。

以下を行うことで、ツールのツリーと対話できます：

• ノードの展開と折りたたみ：特定のワークフロー・セクションへのフォーカス
• ノードのクリック：詳細なタスク情報にジャンプします
• 実行パスの追従：画面を介してデータがどのように流れるかをトレースします
• ボトルネックの特定：ワークフローが非効率になっている場所を見つけます

可視化により、テキスト・ログやトレース・データのみを追おうとするよりも、ワークフローのデバッグが大幅に容易になります。

「Eval（評価）」タブは、エージェント実行の正確性と信頼性を測定する、品質保証および監視のビューを提供します。このステップは、何が起きたかを観察する段階から、それがどれほど良好に起きたかを評価する段階へと移行する場所です。

「Eval（評価）」タブには、ガードレールを通じて品質を評価した評価結果が表示されます：

• タスクの成功：どのタスクが完了し、どのタスクが失敗したか
• 出力品質：出力が期待される結果や品質基準に一致したかどうか
• パフォーマンス・スコア：成功レベルを示す定量的メトリクス
• エラー分析：障害の分類と深刻度
• ユースケースの検証：エージェントの振る舞いが意図したユースケースに一致しているかどうか

評価は、エージェントがどれほど一貫して正しい結果を生成するかを追跡することで信頼性を監視し、変更によってエージェントのパフォーマンスがいつデグレードするかを特定し、改善の優先順位を付け、本番環境へのデプロイメント前にエージェントが正しく動作することを検証して信頼を築くのに役立ちます。

評価の測定値を活用して、アラートの設定、改善の追跡、パターンの特定を行うことができ、プロンプトやツールを改善するための開発をガイドするフィードバックを使用できます。

気象クエリーの15％が評価に失敗していることに気づいた場合、それらの特定のトレースを調査して、問題が不適切な入力処理、APIの失敗、または不正確な応答フォーマットのいずれであるかを理解できます。

「Issues（問題）」タブは、ワークフローの実行中に発生したすべての不具合を集中表示します。このタブは、エージェントの障害や予期しない振る舞いをデバッグする際に最初に確認する場所です。

「Issues（問題）」タブには、以下のような問題がリストされます：

• API呼び出しの失敗：エラーを返す外部サービス
• ツールの実行失敗：クラッシュまたはタイムアウトしたツール
• 入力の欠落：必要なときに利用できない必須データ
• モデルの例外：トークン制限や無効な入力などのLLMエラー
• 検証エラー：期待される形式を満たさないデータ
• タイムアウト・エラー：制限時間を超えた操作
• 未処理のランタイム障害：エージェント・コード内の予期しない例外

上のスクリーンショットでは、気象APIが424（依存関係エラー）または404（見つかりませんでした）のエラーを返したときに発生したツール・エラーを確認できます。「Issues（問題）」タブには、以下が表示されます：

1. エラー・タイプ：「ツール・エラー」
2. 特定のツール：get_weather
3. エラー応答：障害を示す完全なAPI応答
4. ダイレクト・リンク：クリックすると、失敗した正確なタスクにジャンプします

このアプローチにより、ログやトレース・データを掘り下げることなく、何が問題だったかを簡単に理解できます。

「Issues（問題）」タブは、個々のタスクを捜索することを強制される代わりに、障害を集約するため、特に価値があります。完全なエラーの詳細と関連データを含めることで完全なコンテキストを提供する一方、深刻度レベルによって迅速なトリアージが可能になり、どの問題に最初に取組むべきかの優先順位を付けることができます。ソース・タスクへのダイレクト・リンクは、1回クリックするだけで、問題が発生した正確な実行ポイントに移動できることを意味します。

「Trajectory（軌跡）」タブは、ユーザーとエージェントが呼び出すツールとの間のエージェント対話を、時系列の会話スタイルで表示します。このビューは、エージェントの振る舞いの完全なコンテキストとフローを理解するために非常に価値があります。

「Trajectory（軌跡）」ビューは、エージェントがリクエストを最初から最後までどのように処理するかを正確に確認でき、エージェントの振る舞いを完全に可視化できるため有用です。ツールが正しいパラメーターで呼び出され、適切な応答を受信していることを確認することで、ツールの統合を検証できます。予期しない応答をデバッグする際、「Trajectory（軌跡）」はロジックが期待からどこで逸脱したかをトレースするのに役立ちます。また、ワークフローが自然に展開していくのを見ながら、複数の会話のやり取りを通じてコンテキストがどのように構築されるかを分析することもできます。デバッグだけでなく、「Trajectory（軌跡）」は文書としても機能し、チーム・メンバーと共有したり、将来の開発の参考事例として使用したりできる正しい振る舞いの例をキャプチャーできます。このビューは、さまざまなシナリオにわたるエージェントの適応性を検証する必要がある、生成AIを使用して構築を行うチームにとって特に価値があります。

製品画面に表示されているWeather Agentの「Trajectory（軌跡）」について詳しく見ていきましょう：

1. ユーザー・クエリー

会話は、ニューヨーク市の天気に関する明確で具体的なリクエストから始まります。

2. エージェントによるツール呼び出し

エージェントは外部データが必要であることを認識し、気象ツールを呼び出します：

この例は、エージェントがニューヨーク市のおおよその座標を正しく特定し、APIへのリクエストを適切に構造化し、現在の天気に対する適切なフラグを設定したことを示しています。

IBM Telemetryは、この結果を未加工のJSONと、綺麗にパースされた展開可能なツリー・ビューの両方で表示します。

3. ツールによるデータの返却

気象APIは、構造化された気象データで応答します：

この例は、ツールがデータの取得に成功し、応答が期待されるスキーマに従っており、必要なすべてのフィールドが存在していることを示しています。未加工のツールの応答を検査できることは、エージェントがツールの出力を誤解する問題をデバッグするために極めて重要です。

4. エージェントによる結果の要約

最後に、エージェントは構造化されたデータを処理し、自然に応答します。

エージェントは気温と気象コードを正しく抽出し、構造化されたデータを自然言語に変換しました。応答は簡潔であり、ユーザーの質問に回答しています。

「Trajectory（軌跡）」タブは、ユーザー・メッセージ、エージェント・メッセージ、またはツールとの対話のみを表示するための、役割ごとのフィルタリングもサポートしています。また、長い会話の一部を展開または折りたたむことで、重要となる詳細に集中できます。さらに分析やデバッグを行うために、データをJSONとしてエクスポートし、軌跡のステップからリンクされたタスクにジャンプして対応する詳細を確認できます。

これで、watsonx Orchestrateを使用したIBM Telemetryのセットアップ、およびAIエージェントの振る舞いを詳細に監視して分析する方法の学習は完了です。IBM Telemetryは、AIエージェントがどのように思考し、決定し、行動するかに対する完全なオブザーバビリティーを提供するために、複数レイヤーの可視性を提供します。詳細を確認したこれらの機能は、本番環境におけるエージェント運用の効果的なライフサイクル管理、または環境内の他のエージェント・フレームワークとの統合において極めて重要です。

問題が発生した場合や質問がある場合は、ドキュメンテーションを確認してください。最も一般的な問題は、次のトラブルシューティング・ガイドで説明されています。他のユーザーが同様の問題に直面していないか、GitHubの問題を確認することもできます。

IBM Telemetryのようなプラットフォームを通じたエージェントの監視は、AgentOpsのための堅牢なエコシステムを生み出しており、自律型エージェントがSDK、ツール、および外部APIの統合を伴うより複雑なタスクを引き受けるにつれて不可欠となっています。エージェントの振る舞いに関して獲得した可視性により、より信頼性が高く、効率的で、信頼できるAIシステムを作成できます。