UiPath AIエージェント活用ガイド ~ Agent Builder構成の詳解 運用編

前回の開発編では、UiPath Agent Builder を使って **AI エージェントを構築する際に必要なコアコンポーネントの役割**について解説しました。

https://qiita.com/utanesuke/private/d3a8f379086940934f02

本記事では、構築した **AI エージェントの品質をどのように評価し、改善**していくかに焦点を当て、UiPath Agent Builder の機能を活用してそれを実現する方法を紹介します。

UiPath Agent Builderでは、以下の3つの機能が備わっており、作成した AI エージェントの品質の評価、改善、実行の追跡を行うことができます。
- **ヘルス スコア**：エージェントの性能・信頼性をスコア化し、運用上の健全性を定量的に把握できます。
- **評価**：入力と期待される出力を用いて、エージェントの正確性を事前にテストできます。
- **トレース**：エージェントの実行時の処理内容を詳細に記録し、動作分析やデバッグに活用できます。

# 1️⃣ ヘルス スコア

ヘルススコアは、UiPath エージェントの**性能と信頼性を総合的に評価する指標**であり、自動化システム内での有効性を定量的に把握できます。

評価は主に以下の 4 項目に基づいて行われます：
- プロンプト構造（文の目的、長さ、明確さなど）
- ツール・コンテキスト・エスカレーションの利用状況（人の介入の有無など）
- 入出力引数の設計（変数の定義）
- 評価データセット（入力と期待される出力との整合性）

これらの項目は多面的に分析され、各項目に 0〜100 のスコアが付けられます。
さらに、それらを重み付き平均で集計し、最終的なヘルススコアとして表示されます。

以下は、実際のヘルススコア画面の例です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/177240/6832cddc-4a9b-4d67-ac17-fd7764fd7218.png)

##  プロンプト文の改善(例)

プロンプト文を例に、このスコアをどのように活用して改善できるのか見てみましょう！

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/177240/4434bc0b-ac48-49a0-87ea-4e8b02d8f1ed.png)

図に示されているとおり、プロンプト文は次の 5つの観点 から評価されます：

| 評価項目              | 説明                                                                 |
|-----------------------|----------------------------------------------------------------------|
| 明確さ（Clarity）      | システムプロンプトとユーザープロンプトの明確さを評価し、スコアの根拠を示します。     |
| 完全性（Completeness）| エージェントが遂行すべきタスクがどれだけ完全にカバーされているかを評価します。      |
| 一貫性（Consistency）  | 指示内容に矛盾がないか、一貫しているかを確認します。                               |
| 思考の流れ（Chain of Thought）| エージェントのタスクに対して、思考の流れが適切に組み立てられているかを評価します。思考の流れがない場合は減点されます。 |
| デモの整合性（Demos） | デモ（例示）がエージェントのタスクに適切に対応しているかを評価します。デモがない場合は減点されます。 |

上記の[Demos]が`Poor`でしたので、マウスを[Demos]にホバーすると、アドバイスが表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/177240/0d1d3025-9660-4554-ac46-c7825bbae704.png)

この評価では、「エージェントが学習・判断するためには**具体例が不可欠**であり、それが欠けていることが問題」と指摘されています。
具体的に、モデルが「保守要員をどのようなルールで選定するか」を理解するためのガイドが不足しています。特に、「入力と出力のペア（例：どのような条件で誰を選んだか）」が欠如しています。

### プロンプト(Before)

以下が改善前のプロンプト文([Demos]指標が`Poor`):

```
あなたは保守設備のアサインを担当するエージェントです。

以下の <未対応設備一覧> に記載された各設備に対して、  
「保守要員一覧」（コンテキスト情報）を参照し、適切な保守要員A・Bを選定してください。

【選定ルール】：

1. 保守要員A・Bともに、その設備に対して「保守資格を持っている設備名」に含まれている必要があります。
2. AとBは別の人物としてください。
3. 人間関係の衝突（備考欄の内容）を考慮し、相性の悪いペアは避けてください。
4. 適任者が複数いる場合、技術力・協調性・過去の実績などを考慮して判断してください。
5. 必ず「アサイン理由」を簡潔に記載してください（例：「経験豊富」「相性が良いため」など）。

アサイン処理が完了したら、最後に出力した「アサイン結果一覧」を、Slackの[Send Message To Channel]アクティビティを使って設備管理チャンネル（#Infra）に送信してください。

送信メッセージには、各設備に対する保守要員A・Bの割り当て内容とアサイン理由を簡潔にまとめてください。

例：
「アサイン結果をお知らせします。
・設備A：担当Aさん／担当Bさん（理由）
・設備B：...」

Slackへの投稿が完了したら処理終了です。

【補足】：
もし、いずれかの保守要員（AまたはB）が見つからない場合は、  
<保守要員の手動確認> エスカレーションを実行し、対象設備名とアサイン結果を記載してください。


【出力形式】：
[
  {
    "設備名": "〇〇設備",
    "保守要員A": "氏名A",
    "保守要員B": "氏名B",
    "アサイン理由": "ペアを選んだ理由"
  },
  ...
]

必要に応じて、備考欄の人間関係情報も活用しながら、適切な保守体制を構築してください。

```

### プロンプト(After)

ヘルススコアでのアドバイスに従い、以下のような具体例をプロンプトに追加しました。

```
...
---

【デモ（入力例と出力例）】

◆ 未対応設備一覧（一部）：
[
  { "設備名": "ポンプA", "保守期限": "2025-03-01" }
]

◆ 保守要員一覧（一部）：
| 氏名   | 保守資格         | 技術力 | 協調性 | 備考                 |
|--------|------------------|--------|--------|----------------------|
| 佐藤健 | ポンプA, ポンプB | 高     | 中     | 鈴木とは過去にトラブル有 |
| 鈴木翔 | ポンプA          | 中     | 高     |                      |
| 山田花 | ポンプB          | 高     | 高     |                      |

◆ 出力例（アサイン結果）：
[
  {
    "設備名": "ポンプA",
    "保守要員A": "佐藤健",
    "保守要員B": "山田花",
    "アサイン理由": "佐藤は技術力が高く、山田は協調性が高くバランスが取れているため。佐藤と鈴木は相性が悪いため回避。"
  }
]
...
```

その結果、再度ヘルススコアを計算したところ、以下のように改善が見られました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/177240/af79677e-c04d-4168-94f3-20f60276835d.png)

# 2️⃣ 評価

**Evaluation（評価）** は、エージェントが**期待通りに正確に動作するかどうか**を検証するための重要な仕組みであり、特に本番運用前の品質確認に役立ちます。Agent Builder には、評価セットを作成・実行する専用の画面が用意されています。

評価は主に、「入力に対する出力が期待通りかどうか」を検証するために行われ、**入力・出力とアサーション（評価方法）** として定義されます。

エージェントに対する評価セットは、以下の2通りの方法で作成できます：

- **[プレイグラウンド] 画面から作成**:  エージェントを実行した後、その結果を元にすぐ評価を作成できます（必要に応じて修正も可能）。
    - <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/177240/99a62346-1674-40f6-ac3e-e58df28f319d.png" alt="[プレイグラウンド] 画面から実行後に作成" width="500">
 
- **[評価] 画面から直接作成**: 評価データセットをあらかじめ準備し、それぞれのフィールド記入します。
    - <img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/177240/1a19fc68-b7c3-4b0c-8296-96e30f190343.png" alt="[プレイグラウンド] 画面から実行後に作成" width="500">

**アサーションの種類が以下の３種類があります、必要に応じて選んでください:**

| アサーションの種類               | 特徴・用途                                                                                             | 推奨されるケース                                                                 |
|----------------------------------|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| **評価者としての LLM**（既定）     | - **LLM が評価者として出力の品質や正確性を判断**<br>- 完全一致ではなく、文脈や意味を加味した柔軟な評価が可能<br>- 自然言語や複雑な構造を含む出力の検証に最適 | - **自然言語での応答**<br>- **推論を含む出力**<br>- **複雑な構造化データの評価**     |
| **JSON の類似性**                | - 出力が **JSON 構造**である場合に使用<br>- **構造と内容が似ていれば OK** という柔軟性がある<br>- 正確な一致ではなく、主要なフィールドの一致を確認 | - **JSON フォーマットの出力**<br>- **一部フィールドのみを検証したい場合**             |
| **等しい（Equal）**              | - **出力が完全に一致**することを求める評価方法<br>- Boolean 値、数値、文字列のような単純な出力に最適                 | - **true/false の判断**<br>- **数値の正確な一致**<br>- **プリミティブな文字列や配列** |

作った評価セットを実行したら、以下のような結果が確認できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/177240/24395c0c-1963-4d9a-93e1-41d8da4326f5.png)

評価の数の決め方やカバレッジの原則に関しては、以下のページをご参照ください。

https://docs.uipath.com/ja/agents/automation-cloud/latest/user-guide/evaluations#number-of-evaluations

# 3️⃣トレース

トレースは、エージェントの実行中に行われた**アクション、入力、出力、イベント**などを詳細に記録したログです。
各ステップで何が行われ、どのようなデータが処理・生成されたかを把握できるため、**エージェントの動作を可視化・分析**するのに役立ちます。

以下に、**Traces（トレース）の主要な役割**をまとめました：

| No. | 役割                  | 説明                                                                                                                                     |
|-----|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| 1   | アクションの追跡       | エージェントが実行したすべてのアクション（外部システムとの連携、データ取得、意思決定、タスク実行など）を記録します。                                     |
| 2   | 意思決定の流れ         | 特定の判断や結果に至った**思考プロセス**を記録し、透明性を確保。エージェントのロジックや理由を把握するのに役立ちます。                               |
| 3   | エラー検出             | 想定外の結果やエラーが発生した箇所を特定しやすくし、**問題の迅速な解決**を可能にします。                                                       |
| 4   | パフォーマンスの監視   | エージェントの処理速度や成功率、効率などを時系列で把握でき、**継続的な最適化**に活用できます。                                                 |
| 5   | 監査とコンプライアンス | 規制対応や社内ポリシーの遵守が求められる環境において、エージェントの活動記録として活用され、**証跡管理に不可欠**です。                              |
| 6   | テストと評価           | テスト実行中のすべての動作を記録することで、**エージェントの信頼性と正確性の検証**が可能になります。多様な条件下での動作確認に役立ちます。     |

以下のように、どのようにLLMをコールしているか、どんなファイルを参照していたか、トレースで実行の詳細を追跡することができます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/177240/72e0f70b-3430-4c5d-8835-1088b7bf3d37.png)

# 🛠️ エージェント作成のベストプラクティス

ここからは、実際にエージェントを作成する際に役立つ「ベストプラクティス」をご紹介します。
理論だけでなく、「では実際にどう設計すればよいのか？」という疑問に応えるため、現場で活用できる具体的なヒントをまとめました。

信頼性が高く、柔軟に動作し、管理もしやすい──そんなエージェントを目指す方にとって、ぜひ参考にしてください。

| ベストプラクティス                            | 概要・目的                                                                                                                                 | 推奨内容・ポイント                                                                                                                                         |
|-----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| 小さな既存ワークフローから始める              | 既存の自動化プロセスを活用し、リスクを抑えてエージェント設計スキルを段階的に習得                                                     | - 既存業務の棚卸とフロー分解<br>- 明確な判断基準と構造を持つプロセスから着手（例：サポートチケット分類など）                                        |
| 明確なゴールと目的を持つ                       | プロンプト設計の前にエージェントの目的と成果を明確化                                                                                   | - 測定可能な目標の定義<br>- 運用環境とKPIの設定<br>- 成功条件の明文化                                                                                   |
| モジュール型アーキテクチャ設計                | 柔軟かつ再利用可能な構成により、高速な機能統合とタスク分担を可能に                                                                   | - 関心の分離（Separation of concerns）<br>- スキルモジュールの組み合わせ<br>- 標準化されたインターフェース設計                                      |
| 明確で一貫性あるツール命名                    | ツール名はエージェント内で正確に参照されるため、命名は簡潔かつ機能を正確に表現する必要あり                                            | - 小文字+英数字、スペース/記号NG<br>- 例：`web_search`, `code_interpreter`, `document_analysis`, `data_visualization`                                  |
| 構造化されたプロンプトと反復                  | 複雑なタスク分解・推論・エラー処理を含む指示群で、LLMに段階的な処理を促す                                                               | - 明確な役割・手順・理由付け・出力形式の指定<br>- chain-of-thought を活用した思考プロセスの明示<br>- 少ない構成で安定した出力を目指す反復改良      |
| トレースの確認と活用                          | 実行ログをもとに、意思決定・エラー・パフォーマンスなどの可視化と最適化を行う                                                           | - 各ステップの動作追跡<br>- ツール使用傾向や失敗箇所の分析<br>- 定期的レビューで長期的進化と健全性を維持                                           |
| 多様な評価データセットの構築                 | 実世界の複雑性を模した評価により、堅牢なエージェント性能を検証                                                                          | - エッジケースや失敗パターンを含む<br>- ドメイン専門家との連携<br>- 合成/敵対的テストデータも活用                                                   |
| 複数の観点からのエージェント評価              | 精度だけでなく、透明性・創造性・倫理性なども含む包括的な評価フレームワークを整備                                                       | - 技術指標＋定性評価＋安全・倫理要件<br>- 自動評価＋人による確認（Human-in-the-loop）                                                               |
| 自動化の中でエージェントを検証                | 単体テストにとどまらず、**エージェントを自動化ワークフローに組み込んで検証**                                                            | - システム間連携、負荷変動への対応、失敗時の復旧などを含む統合テスト<br>- **UiPath Test Suite** での包括的テスト推奨                              |

# 🔚 最後に
本記事では、UiPath Agent Builder を使ったエージェントの評価・改善・追跡方法をご紹介しました。

ヘルススコア・評価・トレースを活用すれば、より信頼性の高いエージェント運用が可能になります。
ぜひ、自社の自動化プロジェクトにも取り入れてみてください。