- はじめに
- スタート アップ ガイド
- 任意のキャンバスで構築する
- 大文字と小文字で構築
- フローを利用した構築
- BPMN で構築する
- オペレーティング
- 監視
- 最適化中
- 参考情報
外部エージェントのトレース
W3C トレース コンテキストとデータ エクスポートを使用して、Maestro プロセスが呼び出してオブザーバビリティ プラットフォームにつなぎ合わせた外部エージェント内で何が起こっているかを確認します。
問題の説明
Maestro プロセスでは、外部エージェント (Azure AI Foundry、Databricks などのプラットフォームで実行されるエージェント) を呼び出すことが増えています。外部エージェントの呼び出しだけでは、エージェントが実行されたことと、エージェントが成功したかどうかのみが Maestro に伝えられます。内部で何が起こったか (どのモデル、どのツールが使用されたか、各ステップにかかった時間、呼び出しが失敗した理由) は通知されません。
このような可視性がなければ、プロセス オーナーはプロセス内の外部エージェントのステップを監査、最適化、トラブルシューティングできません。外部呼び出しが失敗した場合、ログには境界での結果のみが表示されるため、チームは各外部プラットフォームにログインしてタイムスタンプを推測し、無関係なアクティビティを検索して何が問題だったかを再構築する必要があります。外部エージェントのトレースは、このギャップを埋めます。
外部エージェントのトレースがどのように役立つか
Maestro は、オープンな W3C トレース コンテキスト 標準を使用して分散トレースに参加します。Maestro が行うすべての外部エージェント呼び出しには、共有のトレース ID があります。標準を理解しているエージェントは、同じトレース ID で自身のアクティビティを記録します。そのため、オブザーバビリティ プラットフォームでは、Maestro のステップと外部エージェントの内部ステップを 1 つのエンドツーエンドのビューにつなぎ合わせることができます。
動作のしくみ
- Maestro によってトレース ID が生成されます。プロセス インスタンスが開始されると、Maestro によって実行用の一意のマスター トレース ID が作成されます。
- Maestro はすべてのアウトバウンド呼び出しでこの出力を反映します。外部エージェントを呼び出す前に、Maestro はトレース ID を W3C
traceparentヘッダーとして要求に挿入します (例:traceparent: 00-<trace-id>-<span-id>-01 - 準拠しているエージェントはトレースを続行します。W3C トレース コンテキストをサポートする外部エージェントは、ヘッダーを読み取り、マスター トレース ID を保持し、その内部の作業 (モデルの呼び出し、ツールの使用、遅延、エラー) を同じトレースの子スパンとして記録します。
- スパンは、お使いのオブザーバビリティ プラットフォームへフローします。Maestro のスパンは、 データ エクスポートを介してプラットフォームに到達します。外部エージェントのスパンは、独自のテレメトリ パイプラインを介して到着します。どちらも同じトレース ID を持つため、プラットフォームによって 1 つのウォーターフォール ビューに結合されます。
トレースの反映は、フレームワーク レベルの単一の動作です。これは Maestro 全体にわたる外部エージェントの呼び出しに自動的に適用されます。コネクタごと、またはエージェントごとに有効化する必要はありません。
前提条件
- データ エクスポートを設定するには組織管理者である必要があり、テナントで Insights が有効化されている必要があります。
- サポートされるトレースの宛先 ( Databricks、 Arize、または OTLP (OpenTelemetry プロトコル) エンドポイント。
- 外部エージェントはトレースを出力し、エージェント側でトレースを有効化する必要があります。モデルのみのサービング エンドポイントまたは LLM サービング エンドポイントでは通常、トレースは生成されません。トレースが有効化されているエージェントのみが生成されます。
データ エクスポートを構成する
外部エージェントのトレースは、Maestro の実行トレースがオブザーバビリティ プラットフォームにエクスポートされると表示されます。
- 組織に移動し、[ 管理 ] タブを選択して [ データ エクスポート ] カードを選択します。
- [ + 追加 ] を選択して、設定ウィザードを完了します。
- テナントを選択し、[ エージェント] と [Maestro トレース ] のデータ ソースを選択します。このデータ ソースは、 OTEL トレース データとしてエクスポートされます。
- 接続先 ( Databricks、 Arize、または OTLP エンドポイント ) を選択し、接続の詳細を入力して保存します。
エクスポートがアクティブ化されると、Maestro のトレース (外部エージェントの呼び出しからのスパンを含む) が宛先にストリーミングされ、トレース ID で検索して完全な実行を確認できます。
設定の詳細と宛先固有の手順については、「 データのエクスポート」をご覧ください。
Databricks: Databricks エージェント API は、受信の W3C トレース ヘッダーを受け入れず、代わりに呼び出しごとに独自のトレース ID を発行します。Databricks の呼び出しを関連付けるために、Maestro は呼び出しによって返された Databricks トレース ID をキャプチャし、アクティビティのスパンの下に入れ子になった 外部エージェントの呼び出し のスパンに記録します。これを Databricks 側で機能させるには、以下が必要です。
- エージェントで MLflow トレースを有効化する必要があります。
- トレース ID を UiPath に返すようにエージェントを設定する必要があります。
- MLflow の最新バージョンが必要です。古いバージョンではトレース ID が返されないため、トレースのスパンは生成されません。
よくある質問
外部エージェントに何かをインストールする必要がありますか?
いいえ。Maestro は、オープンな W3C トレース コンテキスト標準を使用してトレース コンテキストを伝搬します。この標準をすでにサポートしている外部エージェントは、そのスパンを Maestro トレース ID で自動的に記録します。エージェントのコードに追加するものは何もありません。
コネクタまたはエージェントごとにトレースを設定する必要がありますか?
いいえ。トレースの反映は、Maestro 全体にわたる外部エージェントの呼び出しに適用される単一のフレームワーク レベルの動作です。必要な設定は、トレースがオブザーバビリティ プラットフォームに到達するようにデータのエクスポート先を設定することだけです。
一部の外部エージェントのトレースは表示されるのに、他の外部エージェントのトレースは表示されないのはなぜですか?
外部エージェントは、実際にトレースを出力した場合にのみトレースを提供します。プレーン モデルまたは LLM のサービング エンドポイントでは通常、トレースは生成されません。トレースが有効化されているエージェントのみが生成されます。W3C トレース コンテキストをサポートするエージェントの場合、そのスパンは自動的に Maestro トレース ID の下に表示されます。そうでないエージェント (Databricks など) については、トレースをエージェント側で有効化して設定し、トレース ID を Maestro に返すようにする必要があります。
トレースはどこで確認できますか?
独自のオブザーバビリティ プラットフォームで。データのエクスポートがアクティブ化されたら、トレース ID で検索して、Maestro のスパンと外部エージェントのスパンを 1 つのエンドツーエンドのビューにつなぎ合わせて確認します。