エージェントのトレース

エージェントのトレースを表示して分析し、エラーやメタデータも含め、完了したエージェント実行のすべてのステップ、判断、データ ポイントを監査します。

トレースについて

トレースは、エージェントが実行中に行ったすべての動作 (実行ステップ、処理されたデータ、決定、生成された結果など) の詳細な記録です。各トレースは、タイムスタンプ、エラー、入力/出力、コンテキストのメタデータなど、エージェントの動作の完全なタイムラインをキャプチャします。 トレースは、以下の場合に使用します。

• デバッグとトラブルシューティング: エージェントが失敗した場所やエージェントが予期しない動作を行った場所を正確に特定します。
• パフォーマンス分析: エージェントの実行全体にわたるレイテンシ、エラー、スループットを評価し、動作を最適化します。
• コンプライアンスと監査: エージェントが何を、いつ、どのように行ったかについて、検証可能な記録を維持します。これは、監査や規制対象のワークフローに不可欠です。
• 継続的な改善: トレースに関するインサイトを使用して、エージェントのロジックの微調整、動作の改良、新しいモデルのトレーニングを行います。

以下の表は、トレースの可視化によってエージェントの動作をデバッグ、分析、最適化する能力を強化できる、一般的なユース ケースの概要を示しています。各例では、開発中および実行時の監視中に、トレース データがどのようにインサイトを明らかにし、より適切な意思決定を促進するかを示しています。

ユースケース	トレースの利用方法
ツールの呼び出し中にエージェントが失敗する	正確なステップ、入力、出力、およびエラーを見つけて検証する
パフォーマンスが遅い	タイムスタンプを使用してボトルネックを特定する
エラーの急増を調査する	実行をステータスでフィルター処理し、パターンをトレースする
運用環境の修正を検証する	元の実行を再現し、問題が発生しなくなったことを確認する
監査レポートを準備する	意思決定の経路と処理したデータを示すトレースをエクスポートまたは確認する

トレースの種類

トレースには 2 つの異なる種類があり、エージェントの動作を把握して分析する上で、それぞれが特定の目的を果たします。

• エージェントの実行のトレース: このトレースは、ライブ実行中やスケジュール設定された実行中に、エージェントのステップごとの実行をキャプチャします。エージェントがどのようにデータを処理し、ツールを呼び出し、条件を処理し、さまざまなステートにリアルタイムで応答したかが分かります。
• 評価の実行のトレース: 評価のトレースは、定義済みの入力に対してエージェントをテストするときに生成します。通常は、モデルの評価、シナリオの検証、またはテスト ケースの実行時に使用します。エージェントの正確性、意思決定の品質、および制御された条件下での動作を評価するのに役立ちます。

トレースにアクセスする

どちらの種類のトレースにも、次の 2 つの主要な場所からアクセスできます。

• Agent Builder – エージェントの設計またはテスト中に、トレースをビルダーで直接利用できます。
  • エージェントを実行すると、下部のパネルが自動的に開いて [実行証跡] タブに移動し、現在の実行のライブ トレースが表示されます。[履歴] タブに切り替えて過去の実行を表示し、評価セットに実行を直接追加することもできます。
  • [評価] タブと [出力] タブには、最近の実行の別のビューで表示され、動作と結果をエージェントの定義と併せて検査できます。
• [エージェント インスタンス] ページ – [Agents] > [インスタンス] セクションに移動します。ここから、特定のエージェントを選択して任意の実行を選択し、そのトレース ビューを開くと、視覚的な完全なトレースと [ログ] パネルが表示されます。

エージェントの実行でも評価の実行でも、トレースを表示すると、エージェントの実行を可視化できます。以下が可能です。

• 色分けされたノードで示される実行結果 (成功、失敗、またはリトライ) を確認できます。
• 任意のノードにカーソルを合わせると、開始と終了のタイムスタンプ、実行ステータス、入力スニペットと出力スニペットのプレビューが表示されます。
• ノードを選択すると、完全な JSON ペイロード、ログとエラー、実行時のメトリック (トークンの使用状況、レイテンシ) などの詳細が表示されます。

Traces for the external agents your Maestro processes invoke, such as agents running in Azure AI Foundry or Databricks, are available in your own observability platform through Data Export. For details, refer to External agent traces.

ライセンスの可視性

注:

この機能はプレビュー版として利用可能です。トレースではサポートされているサービスの消費状況が報告されますが、まだすべてのサービスにコストを表示できるわけではありません。消費量とコストの信頼できる情報源については、 ライセンスに関するページをご覧ください。

トレースには、実行がライセンス権利からどれだけの金額をスパンごとに引き出すかが示されます。消費するスパンでは、スパン名の横に使用状況バッジが表示され、引き出された金額と単位が示されます。

消費量は、請求対象の操作を実行するスパンで報告されます。エージェントの実行の場合、これは各 LLM 呼び出し内のモデル実行の範囲になります。バッジのないスパンは必ずしも無料ではありません。そのコストは、子スパンの 1 つで報告されるか、バッジが表示されている最も近い親の合計に含まれます。

スパンを選択して [ メタデータ ] タブを開くと、[ 使用状況 ] セクションに金額と単位が表示されます。

トレースに表示されるユニット

バッジに表示される内容	意味
エージェント ユニットまたはプラットフォーム ユニット	通話は、組織が購入したユニットから引き出されました。フレックスのエージェント ユニットとユニファイド プライシングのプラットフォーム ユニットのうち、これら 2 つのどちらが表示されるかはライセンス プランによって異なります。
AgenticPool.UnifiedTokens	呼び出しは、ユーザー ライセンスに含まれる AI およびエージェンティックの使用状況プールから取得されました。プールにはまだ表示名がないため、内部コードとして表示されます。

消費の取得元です。

• 設計時 — デバッグの実行と評価は、まず AI とエージェンティックの使用状況プールから差し引かれ、月間制限を使い切ったら購入したユニットから差し引かれます。
• 実行時 — デプロイされた実行は、購入したエージェント ユニットまたはプラットフォーム ユニットから差し引かれます。LLM の呼び出しあたりのレートはモデルのティアによって異なります。

ツールの呼び出し、添付ファイル、サーバーレス操作などの LLM 以外の追加の呼び出しは、プレビューの過程でサポートされるものとして含まれます。

表示されている金額は、組織に請求される金額です。契約に割引消費率が含まれている場合、ライセンスのページに記載されている標準料金よりも低くなります。

これらの値の背後にあるレートの詳細については、「 ライセンス」ページを参照してください。月間制限、トップアップ、有料ユニットのフォールバックの仕組みについては、「 AI とエージェンティックの使用状況プール」をご覧ください。

トレース データに対するアクセス権を管理する

このセクションでは、管理者がロールベースのアクセス制御モデルを使用してトレース データに対するアクセス権を設定する方法について説明します。

To view traces, you need the following permissions:

• Logs.View
• Jobs.View

既定のロールの権限の詳細については、「既定のロール」を参照してください。

次のマトリクスは、権限の組み合わせによって可視性がどのような結果になるかについて説明しています。これらの組み合わせにより、ロールベースの権限に応じて表示できるトレースの詳細が定義されます。

Logs.View	Jobs.View	アクセス権の結果
有効化	有効化	すべての属性
有効化	無効化	すべての属性
無効化	有効化	一部の属性 (例: name、type)
無効化	無効化	アクセス権限なし。

トレース データを表示するために必要な権限がない場合は、メッセージが表示され、アクセスが完全に制限されているか、それとも部分的に制限されているかが説明されるとともに、必要な権限を要求するためのガイダンスが提供されます。

注:

入力データと出力データなどのトレース データは、顧客管理のキー (CMK) を使用して暗号化できます。エージェント トレースの CMK 暗号化はオプトイン型機能であり、組織で CMK を構成していても自動的には有効になりません。これを有効にするには、サポート チケットを送信します。詳しくは、管理ガイドの「サービスごとの暗号化」をご覧ください。

エージェントの実行に関するフィードバック

注:

この機能はプレビューで利用可能です。

フィードバックは、エージェントのランタイムを解釈して改善するための重要なメカニズムです。フィードバックにより、動作を確認して問題を診断し、エージェントがどのように意思決定を行うかという点で意味のあるパターンを文書化できます。

フィードバックは、デバッグ以外に、フィードバックベースのエピソード メモリへの中心的なインプットとしても機能します。このため、調整を行うたびにプロンプト全体を書き直さなくても、エージェントは意思決定ポリシーを段階的に改良できます。

フィードバックとメモリの関係

フィードバックは注釈ツールとして機能しますが、その最も強力な用途はエピソード メモリに影響を与えることです。

トレースについてのフィードバックを提供することで、エージェントが今後の実行で再現または回避すべき動作を示します。フィードバックの保存方法と再現方法については、「 エージェント メモリ」をご覧ください。

• 繰り返しによる進化: 静的な解決策とは異なり、フィードバックベースのメモリでは、エージェントの動作を時間の経過とともに改善できます。エージェントは学習によって、正しいまたは正しくないとしてフラグが付けられたパターンを認識します。
• 対象を絞った改善: このアプローチは、エージェントがほとんどの場合に「ほぼ正しい」フローや、意思決定ポリシーがまだ開発段階であるフローで最も役に立ちます。
• 選択的メモリ: すべてのフィードバックが自動的にメモリになるわけではありません。どの注釈が価値の高い学習機会に相当するかをユーザーが能動的に判断し、低品質のフィードバックや一貫性のないフィードバックによってパフォーマンスが低下するのを防ぐ必要があります。

フィードバックを適用する場所

エージェント トレース内の任意の範囲に対してフィードバックを提供できます。この柔軟性により、動作を確認または診断する際に、特定のツールの呼び出し、ガードレールの確認、LLM 出力への注釈追加ができます。

エピソード メモリの対象となるのは、エージェントの実行の範囲に適用されたフィードバックのみです。分析のためにトレースの任意の部分に注釈を付けることができますが、メモリとして保存され、今後の実行で取得されるのは、エージェントの実行の範囲に直接関連するフィードバックのみです。

フィードバックを適用すべき状況

すべてのトレースにフィードバックを提供すると反復学習は最大化されますが、現実的には、最適化に最高の価値を提供するトレースに集中することをお勧めします。

以下のシナリオに重点を置きます。

• 重要なシナリオ: 重要な意思決定や影響の大きいエラーを含むトレース。
• 繰り返し発生するパターン: エージェントが常に苦労しているか、繰り返しエラーが発生する領域。
• 難しい意思決定: エージェントが複雑な選択に直面した事例。
• 否定的な感情: 質の低いユーザー エクスペリエンスにつながった実行。
• モデルの動作: エージェントに厳密に模倣または回避させる特定の動作を明確に示す例。

継続的な改善のためにはフィードバックを適用することが不可欠です。これにより、より優れた動作を段階的にエンコードして、エージェントの実行の信頼性と一貫性を向上できます。

• トレースの優先順位の設定: 重要なシナリオ、影響の大きいエラー、またはエージェントが苦労している繰り返し発生するパターンのトレースに重点を置きます。
• 価値の高いシナリオ: エージェントにとって難しい意思決定を表す実行、ユーザーの否定的な感情を示す実行、またはエージェントに模倣または回避させる動作を明確に示す実行を優先します。
• 重視する領域: フィードバックを提供している領域を明確に指定します。
  • アウトプット: 最終的な結果が期待を満たしていたかどうか。
  • 計画の実行 (軌跡): エージェントはタスクのステップを期待された順序で実行したかどうか。
  • コメント: コメントを使用して、フィードバックを強化し、メモリの取得に情報を提供します。

トレースの Time-To-Live 設定

Automation Ops の AI Trust Layer ポリシーを使用すると、Time-to-Live (TTL) を指定することでトレースのスパンを保持する期間を設定できます。

トレースの Time-to-Live では、AI Trust Layer での実行トレースの保持期間を定義します。各トレースは、オートメーションまたは AI との対話のステップを記録するスパンで構成されます。TTL 設定により、これらのスパンが利用可能な期間を指定し、選択した期間より古いスパンを自動的に削除します。TTL は、有効化した後に記録されたトレースにのみ適用されます。

By default, TTL enforcement is off and spans are kept for 90 days. When you enable it, you can shorten the retention window to 1 day or 7 days. There is no option to specify an arbitrary number of days. Choose the option that best aligns with your privacy, compliance, and operational requirements.

ポリシーはテナント レベルで適用されます。つまり、設定されている TTL はすべてのスパンに適用され、テナント内のすべてのユーザーが参照できる内容に影響します。

Agent traces follow this retention however the agent runs, including when a Maestro agentic process or a Maestro Automate workflow calls the agent. How long the calling process or workflow keeps its runs does not change how long the agent trace is kept.

AI Trust Layer の [機能トグル] にある Automation Ops ポリシーの設定で、TTL の適用を有効化または無効化できます。

• 有効化されている場合: トレースのスパンは [TTL 日数] フィールドで選択した期間 (1 日または 7 日) 保持され、その期間が経過すると自動的に削除されます。
• When disabled: spans are kept for the default period of 90 days.

トレースの TTL を有効化して設定するには、次の手順を実行します。

1. Automation Ops に移動します。
2. まだ AI Trust Layer ポリシーがない場合は、[製品ポリシーを追加] – [AI Trust Layer] を選択します。既存のポリシーがある場合は、ポリシーを開いて編集します。
3. [機能トグル] を選択します。
4. 次のフィールドを設定します。
   • トレース データへの Time-To-Live (TTL) の適用 – 有効化した場合、スパンを参照できる期間を制御します。この期間を過ぎると、スパンは削除されます。TTL の有効期限が切れると、影響を受けるスパンはすべて UI から完全に削除されます。
     • TTL 日数 – トレースのスパンを、それを削除する時点まで保持する期間を指定します。[1 日] または [7 日] を選択します。
   • Insights のトレース データを制限 – 有効化すると、UiPath 以外のすべてのメタデータが、Insights に送信される前にトレース データから削除されます。これは、Insights で利用できる詳細を制限し、[Agents] ページで詳細なまたは集計されたメトリックを表示する機能に影響します。

注:

トレース内の任意のスパンにフィードバックまたはメモリが追加された場合は、トレース全体が保持され、設定されている TTL は適用されなくなります。トレースをクリーンアップできるようにするには、まず関連するフィードバックまたはメモリを削除する必要があります。

トレースのガバナンスへの影響

トレース データにカスタム TTL を設定すると、以下のような重要な影響があります。

• 分析: TTL 設定によって、分析に使用できる履歴トレース データの量が決まります。保持期間を短くすると、より厳格なデータ最小化の要件がサポートされ、長くすると、調査やトラブルシューティングのために保持される実行コンテキストが増えます。
• データの削除: スパンは、設定されている TTL を超えると自動的に削除されます。TTL を変更しても、すでに有効期限が切れているデータや制限されているデータは復元されません。
• 可視性: TTL の期間外になる実行の実施は、トレースの UI や、スピード レイヤーのトレース データに依存するコンポーネントに表示されなくなります。
• 範囲: 設定されている TTL はテナント内のすべてのスパンに適用され、すべてのユーザーの可視性に影響します。
• 例外: エージェント メモリやトレースのフィードバックなど、一部の機能は TTL を完全にバイパスする場合があります。これらの機能のデータは、専用の終了ポリシーが定義されるまで無期限に保持されます。

トレースのトラブルシューティング TTL

ジョブにトレースがない

Trace retention and job retention are separate settings. Your AI Trust Layer policy controls how long trace spans are kept, and the Orchestrator retention policy controls how long jobs are kept. If your trace TTL is shorter than your job retention period, a job stays in Orchestrator after its trace is deleted.

たとえば、トレースの TTL が 1 日で、完了したジョブの保持期間が既定で 30 日間の場合、3 日前に実行されたジョブは引き続き Orchestrator に表示されますが、そのトレースは利用できなくなります。ジョブの保持について詳しくは、「 プロセスのデータ保持ポリシー」をご覧ください。

トレースに有効期限メッセージが表示される

AI Trust Layer ポリシーで設定された TTL よりも古いジョブのトレースを開くと、トレースに次のメッセージが表示されます 。ガバナンス ポリシーによっては、このジョブのトレースの有効期限が切れている可能性があります。

TTL を有効化した後にトレースが記録された場合、そのスパンは削除され、復元できません。TTL を有効化する前にトレースが記録された場合でも、そのスパンが表示されます。詳しくは、「 TTL を有効化した後も古いトレースが表示されます」をご覧ください。

TTL を有効化した後も、古いトレースが表示されます

TTL を有効化する前に記録されたトレースでは、記録されたときに適用された保持期間が保持されます。

• トレースのリストには、新しい TTL ウィンドウ内のトレースのみが表示されます。
• 古いトレースを、たとえば Orchestrator のジョブから直接開くことはできます。
• これらのトレースはオンデマンドで削除することはできません。元の保持期間が終了すると削除されます。