エージェントのトレース

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

トレースについて

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

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

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

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

トレースの種類

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

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

トレースにアクセスする

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

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

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

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

Licensing visibility

注:

This feature is available in preview. Traces report consumption for supported services, but not all services can display costs yet. For the authoritative source of consumption and costs, refer to the Licensing page.

Traces show how much a run draws from your licensing entitlement, span by span. Spans that consume display a usage badge next to the span name, showing the amount and the unit it is drawn from.

Consumption is reported on the span that performs the billable operation. For an agent run, this is the Model run span inside each LLM call. A span without a badge is not necessarily free. Its cost is either reported on one of its child spans, or included in the total on the nearest parent that shows a badge.

Selecting a span and opening the Metadata tab shows the amount and unit in the Usage section.

Units shown in traces

What the badge shows	意味
Agent Units or Platform Units	The call was drawn from the units your organization purchased. Which of the two appears depends on your licensing plan: Agent Units on Flex, Platform Units on Unified Pricing.
AgenticPool.UnifiedTokens	The call was drawn from the AI and Agentic usage pool included with your user license. The pool does not have a display name yet, so it appears as its internal code.

Where consumption is drawn from

• Design time — debug runs and evaluations draw from your AI and Agentic usage pool first, and from purchased units once the monthly limit is spent.
• Run time — deployed runs draw from purchased Agent Units or Platform Units, at a rate per LLM call that depends on the model tier.

Additional non-LLM calls, such as tool calls, file attachments, and serverless operations, will be included as supported over the course of the preview.

The amount shown is what your organization is charged. If your contract includes a discounted consumption rate, it is lower than the standard rate published on the Licensing page.

For details regarding the rates behind these values, refer to the Licensing page. For how the monthly limit, top-ups, and paid-unit fallback work, refer to AI and Agentic usage pool.

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

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

トレース ログを表示するには、次の権限が必要です。

• 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 設定により、これらのスパンが利用可能な期間を指定し、選択した期間より古いデータを自動的に削除します。

Time-To-Live (TTL) の適用には、オフ、1 日間の保持期間を経てオン、7 日間の保持期間を経てオンの 3 つの固定オプションがあります。任意の保持期間日数を指定できるオプションはありません。プライバシー、コンプライアンス、運用上の実際の要件に最も適したオプションを選択します。

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

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

• 有効化されている場合: トレースのスパンは [TTL 日数] フィールドで選択した期間 (1 日または 7 日) 保持され、その期間が経過すると自動的に削除されます。
• 無効化されている場合: トレースに厳密な TTL ポリシーは適用されません。

トレースの 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 を完全にバイパスする場合があります。これらの機能のデータは、専用の終了ポリシーが定義されるまで無期限に保持されます。