クライアント側のツール

クライアント側のツールはユーザーのブラウザーまたはホスト アプリケーションで実行されるため、サーバー側では利用できないクライアント ローカル データやデバイス機能にアクセスできます。

クライアント側のツールは、UiPath サーバー上ではなくクライアント画面 (ユーザーのブラウザーまたはホスト アプリケーション) で実行されます。エージェントがクライアント側のツールを呼び出すと、ランタイムは一時停止し、ツールの呼び出しをクライアントに委任し、クライアントが結果を返すと再開します。

クライアント側のツールは、エージェントが、クライアント上にのみ存在するデータや機能 (アプリケーションのステート、ローカル データ、サーバー側では実行できない UI アクションなど) にアクセスする必要がある場合に使用します。

クライアント側のツールを使用すべき状況

クライアント側のツールは、エージェントが以下が必要な場合に使用します。

• クライアント ローカル データへのアクセス — ホスト アプリケーションから、タスク ボードの内容、フォーム フィールド、セッション固有のステートなどの情報を読み取ります。
• クライアント側のアクションをトリガー する — ページへの移動、ダイアログを開く、ローカル UI でのレコードの作成、コンポーネントの更新などのアクションをホスト アプリケーション内で実行します。
• クライアント固有の機能を活用 する — クリップボードへのアクセス、ローカル ストレージ、位置情報など、サーバーからアクセスできないデバイスやブラウザーの機能を使用します。

注:

クライアント側のツールは、 UiPath TypeScript SDK や UiPath 会話プロトコルを実装するサーフェスなど、クライアント側のツールの処理をサポートするサーフェスを介してデプロイされた会話型エージェントでのみ使用できます。サーフェスは、クライアント側ツールごとにハンドラーを登録する必要があります。ハンドラーが登録されていないツールは、エージェントにエラーを返します。

クライアント側ツールを設定する

会話型エージェントにクライアント側のツールを追加するには、以下の手順を実行します。

1. エージェント デザイナーで [ツールを追加] を選択します。

2. [ クライアント側のツール ] カテゴリを選択します。

3. 次のフィールドに入力します。

   • ツール名 — ツールの一意の名前です。文字またはアンダースコアで始まる必要があり、含めることができるのは文字、数字、スペース、アンダースコアのみです。
   • 説明 — ツールの機能と使用状況の説明を入力します。この説明により、エージェントはツールを呼び出すかどうかを決定します。
   • 入力スキーマ — ツールを呼び出すときにエージェントがクライアントに渡すパラメーターを定義する JSON スキーマ オブジェクトです。
   • 出力スキーマ — クライアントがエージェントに返す結果の構造を定義する JSON スキーマ オブジェクトです。

   

4. [作成] を選択します。

ツールを作成したら、ツールの [プロパティ] パネルで追加の設定を行えます。

• ツールの名前、説明、スキーマを編集します。
• ガードレールを適用してランタイム ポリシーを適用します。
• ツール呼び出しの確認を有効化して、実行前にユーザーの承認を要求します。

入力スキーマと出力スキーマ

両方のスキーマが必須であり、有効な JSON スキーマ オブジェクトである必要があります。エージェントとクライアントの間の契約を次のように定義します。

• 入力スキーマでは、エージェントがツールを呼び出すときにクライアントに送信するデータを指定します。エージェントは、会話のコンテキストとスキーマ定義に基づいて入力値を設定します。
• 出力スキーマは、ツールの実行後にクライアントがエージェントに返すデータを指定します。エージェントはこの結果を使用して推論を続行します。

スキーマの例

プロジェクト ボードからタスクを読み取るツールの場合:

入力スキーマ:

{
  "type": "object",
  "properties": {
    "boardId": {
      "type": "string",
      "description": "The ID of the task board to read from"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in-progress", "done"],
      "description": "Filter tasks by status"
    }
  },
  "required": ["boardId"]
}

出力スキーマ:

{
  "type": "object",
  "properties": {
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "string" },
          "assignee": { "type": "string" }
        }
      }
    }
  }
}

事前に構築されたサーフェスでの動作

インスタンスの管理や iFrame の埋め込みなどの事前構築済みのサーフェスでは、クライアント側のツールによって、出力スキーマに基づいてフォームがユーザーに表示されます。ユーザーはフィールドに手動で入力し、結果をエージェントに送信します。

クライアント側ツールの最大価値は、 UiPath TypeScript SDK で構築されたカスタム サーフェスで実現されます。ホスト アプリケーションは、プログラムによってツールの呼び出しを処理します。つまり、データの読み取り、アクションのトリガー、ローカル システムとの対話など、ユーザーによる手動入力が不要です。

実行時のクライアント側ツールの動作

エージェントが会話中にクライアント側のツールを呼び出すと、以下のようになります。

1. エージェントは、会話のコンテキストとツールの説明に基づいて、ツールの使用を決定します。
2. ツール呼び出しの確認が有効化されている場合、ツールを続行する前に、ユーザーは提案された入力を確認して承認します。
3. ランタイムが、ツール名、入力値、入力/出力スキーマを含むツール呼び出しをクライアント画面に送信します。
4. クライアント サーフェスは、指定された入力を使用して、ツールに対して登録済みハンドラーを実行します。
5. クライアントは結果をランタイムに返します。
6. エージェントは結果を受け取り、推論を続行します。

ツール呼び出しの確認

クライアント側のツールを実行する前にユーザーの確認を求めることができます。これは、タスクの作成、レコードの更新、現在のページからの移動など、目に見える副作用を伴うアクションを実行するツールで便利です。

クライアント側ツールの確認を有効にするには、以下の手順を実行します。

1. エージェント デザイナーでクライアント側のツールを選択します。
2. ツールのプロパティで、[ 確認が必要] を有効化します。

有効化すると、エージェントはツールを実行する前に一時停止し、提案された入力パラメーターをユーザーに表示されます。ユーザーは、入力を承認、変更、またはツールの呼び出しを拒否できます。

例: プロジェクト計画アシスタント

タスク管理アプリケーションに組み込まれたプロジェクト計画アシスタントについて考えてみましょう。このエージェントには、次の 2 つのクライアント側ツールがあります。

• read_board_tasks — ホスト アプリケーションのユーザーのタスク ボードから現在のタスクを読み取ります。
• create_task — ユーザーのボードに新しいタスクを作成します。

クライアントからデータを読み取る ユーザーが「次は何に取り組むべきですか?」と尋ねると、エージェントは read_board_tasksを呼び出します。ホスト アプリケーションはボードの状態を読み取り、タスク データを返します。次に、エージェントはタスクを分析し、ステータス、期限、依存関係に基づいて優先順位を提案します。

クライアントへのデータの書き込み ユーザーが「金曜日までに第 3 四半期のレポートを確認するタスクを追加してください」と尋ねると、エージェントはタイトル、説明、期限を指定して create_task を呼び出します。確認が有効な場合、ユーザーは提案されたタスクの詳細を最初に確認します。ホスト アプリケーションがボード上にタスクを作成し、エージェントはタスクが作成されたことを確認します。

制限事項

• クライアント側のツールの実行は、クライアント サーフェスの可用性と応答性によって異なります。ツールの実行中にクライアントが切断されると、ツールの呼び出しが失敗する可能性があります。
• クライアント サーフェスは、エージェントが定義するクライアント側ツールごとにハンドラーを登録する必要があります。ハンドラーがない場合、ツール呼び出しはエージェントにエラーを返します。