UiPath UiPath Coded Apps TypeScript SDK入門（第2回）既存のサンプルプロジェクトの解説と活用方法

前回の記事では、UiPath TypeScript SDKの導入と環境構築、そしてセットアップ手順をステップバイステップ解説しました。

TypeScript SDKを理解し、開発環境が整ったことで、UiPathプラットフォームと連携するWebアプリケーションやConversational Agentの実装準備が整いました。

しかし、実際のプロジェクトではゼロからすべてを作る必要はありません。
UiPath公式が提供するTypeScriptベースのサンプルプロジェクトを活用することで、初期実装の手間を大幅に省き、アーキテクチャやベストプラクティスの雛形をそのまま利用できます。

本記事（第2回）では、以下の2つのサンプルプロジェクトを取り上げ、

• UiPath Maestro Process Management App
  （UiPath MaestroのProcessとTypeScriptによるフロントエンド連携サンプル）
• UiPath Conversational Agent App
  （Conversational Agentと連携するためのサンプル）

それぞれの構成と役割を簡単に解説した上で、既存サンプルをベースに実装を効率化する方法を紹介します。

サンプルをそのまま使うだけでなく、

• 構造を理解し
• プロジェクトに合わせてカスタマイズし
• 実務で活用できる形に拡張する

ためのポイントも解説します。

これにより、フロントエンドからUiPathプラットフォーム（Apps / Agents / APIs）への連携を、ゼロから構築するより短時間で立ち上げられるようになります。

本記事では「サンプルを使いこなし、実装を省力化すること」をテーマに進めていきます。

UiPath Maestro Process Management Appの設定と実行

UiPath Maestro のプロセスを OAuth 認証を用いて管理するための、React + TypeScript によるサンプルアプリケーションです。

インストールガイドは以下のページを参照してください。

前提条件やSDK、及びUiPath Cloudでの外部アプリケーションの作成について、前回の記事UiPath TypeScript SDK入門（第1回）環境構築とセットアップ手順を参照してください。

外部アプリケーションのRedirect URI及びスコープは上記のインストールガイドに合わせてください。特に開発する際に、必要なスコープはこちらのページをご参照ください。

プロジェクトフォルダの環境設定

まず、環境変数のテンプレートファイルをコピーします。

PS C:\UiPath-Dev\process-app-v0> cp .env.example .env

次に、.env ファイルを開き、自身の UiPath 環境に合わせて設定を更新します。

VITE_UIPATH_CLIENT_ID=fa6850e3-be12-****************
VITE_UIPATH_ORG_NAME=uta_test
VITE_UIPATH_TENANT_NAME=DefaultTenant
VITE_UIPATH_BASE_URL=window.location.origin
VITE_UIPATH_REDIRECT_URI=http://localhost:5173
VITE_UIPATH_SCOPE=OR.License OR.License.Read OR.License.Write OR.Settings OR.Settings.Read OR.Settings.Write OR.Robots OR.Robots.Read OR.Robots.Write OR.Machines OR.Machines.Read OR.Machines.Write OR.Execution OR.Execution.Read OR.Execution.Write OR.Assets OR.Assets.Read OR.Assets.Write OR.Queues OR.Queues.Read OR.Queues.Write OR.Jobs OR.Jobs.Read OR.Jobs.Write OR.Users OR.Users.Read OR.Users.Write OR.Administration OR.Administration.Read OR.Administration.Write OR.Audit OR.Audit.Read OR.Audit.Write OR.Webhooks OR.Webhooks.Read OR.Webhooks.Write OR.Monitoring OR.Monitoring.Read OR.Monitoring.Write OR.ML OR.ML.Read OR.ML.Write OR.Tasks OR.Tasks.Read OR.Tasks.Write OR.Analytics OR.Analytics.Read OR.Analytics.Write OR.Folders OR.Folders.Read OR.Folders.Write OR.BackgroundTasks OR.BackgroundTasks.Read OR.BackgroundTasks.Write OR.TestSets OR.TestSets.Read OR.TestSets.Write OR.TestSetExecutions OR.TestSetExecutions.Read OR.TestSetExecutions.Write OR.TestSetSchedules OR.TestSetSchedules.Read OR.TestSetSchedules.Write OR.TestDataQueues OR.TestDataQueues.Read OR.TestDataQueues.Write OR.Hypervisor OR.Hypervisor.Read OR.Hypervisor.Write OR.AutomationSolutions.Access PIMS DataFabric.Schema.Read DataFabric.Data.Read DataFabric.Data.Write

インストールと起動

① vite.config.ts の設定変更

vite.config.ts の以下の箇所で、orgName を自分のOrganization名に変更します。

server: {
  proxy: {
    // '/your-org' を実際のOrganization名に変更してください。こちらがuta_testです。
    '/uta_test': {
      target: 'https://cloud.uipath.com',
      changeOrigin: true,
      secure: true,
    },
  },
}

なぜこの設定が必要か？

ローカル開発環境では、ブラウザのCORS制限によりAPIリクエストがブロックされる場合があります。

この設定では、Viteの開発サーバーにローカルプロキシを作成し、UiPath CloudへのAPIリクエストを中継することで、CORS問題を回避しています。

② 依存関係のインストール

以下のコマンドで必要なパッケージをインストールします。

npm install

③ 開発サーバーの起動

npm run dev

起動後、ブラウザで以下のURLを開きます。

http://localhost:5173

アプリケーションを起動したら、以下の手順で認証を行います。

• 「Sign in with UiPath」ボタンをクリックします。
  

• UiPath Cloudの認証画面へリダイレクトされます。

• ログインが成功すると、アプリのダッシュボード画面へ戻ります。
  
  

上記のように、接続先のUiPath CloudでのMaestroプロセスのステータスを確認することができます。

UiPath Conversational Agent Appの設定と実行

UiPath Conversational Agents と連携するための、React + TypeScript によるサンプルアプリケーションです。

WebSocket を利用したリアルタイムのストリーミング応答、会話管理、ファイル添付、ツール呼び出しの可視化、フィードバック機能などを備えています。

インストールガイドが以下のページを参照してください。

前提条件やSDK、及びUiPath Cloudでの外部アプリケーションの作成について、前回の記事UiPath TypeScript SDK入門（第1回）環境構築とセットアップ手順を参照してください。

外部アプリケーションのRedirect URI及びスコープは上記のインストールガイドに合わせてください。特に開発する際に、必要なスコープはこちらのページをご参照ください。

プロジェクトフォルダの環境設定

まず、環境変数のテンプレートファイルをコピーします。

PS C:\UiPath-Dev\conversational-agent-app> cp .env.example .env

次に、.env ファイルを開き、自身の UiPath 環境に合わせて設定を更新します。

VITE_UIPATH_BASE_URL=https://cloud.uipath.com
VITE_UIPATH_CLIENT_ID=fa6850e3-be12-****************
VITE_UIPATH_REDIRECT_URI=http://localhost:5173/callback
VITE_UIPATH_SCOPE=OR.Execution OR.Folders OR.Jobs ConversationalAgents Traces.Api
VITE_UIPATH_ORG_NAME=uta_test
VITE_UIPATH_TENANT_NAME=DefaultTenant

インストールと起動

① 依存関係のインストール

以下のコマンドで必要なパッケージをインストールします。

npm install

② 開発サーバーの起動

npm run dev

起動後、ブラウザで以下のURLを開きます。

http://localhost:5173

アプリケーションを起動したら、以下の手順で認証を行います。

• 「Sign in with UiPath」ボタンをクリックします。
  

• UiPath Cloudの認証画面へリダイレクトされます。

• ログインが成功すると、アプリのダッシュボード画面へ戻ります。
  
  

上記のように、接続先のUiPath CloudでのConversationalAgentを利用することができます。

補足

以下のファイル構成や解説は2026年2月24日時点のサンプルプロジェクトに基づいて、OpenAIのCodexを使って解析したものです。

UiPath Maestro Process Management Appの解説

このサンプルは、Maestro の「プロセス一覧表示」「プロセス実行」「実行状況モニタリング」など、プロセス管理アプリの基本機能をフロントエンドで実装するための出発点として最適です。

サンプルの構成（フォルダ・ファイル）

• ルート:

ファイル	役割
.env	ローカル用の実環境変数（OAuth情報など、機密値）。
.env.example	.env のテンプレート。
.gitignore	Git管理から除外するファイルの定義。
eslint.config.js	ESLintルール設定。
index.html	SPAのHTML土台。#root と main.tsx 読み込み。
package.json	依存関係と dev/build/lint/preview スクリプト定義。
package-lock.json	依存パッケージの厳密バージョン固定。
postcss.config.js	Tailwind/Autoprefixer の PostCSS 設定。
README.md	セットアップ・OAuth手順・使い方の説明。
tailwind.config.js	Tailwindのスキャン対象などテーマ設定。
tsconfig.json	TypeScriptプロジェクト参照の親設定。
tsconfig.app.json	アプリ本体向けTypeScript設定。
tsconfig.node.json	Vite設定ファイル向けTypeScript設定。
vite.config.ts	Vite設定（React、path-browserify、UiPath SDK最適化、ローカルプロキシ）。

• src/-

ファイル	役割
src/main.tsx	Reactエントリポイント。App を #root にマウント。
src/App.tsx	画面全体の制御。認証状態でログイン画面/メイン画面を切り替え。
src/App.css	Vite初期テンプレ由来のスタイル（実運用ではほぼ未使用）。
src/index.css	Tailwind読み込みとグローバルCSS。
src/vite-env.d.ts	Vite型定義参照。

• src/assets/-

ファイル	役割
src/assets/favicon.png	ブラウザタブのアイコン。

• src/hooks/-

ファイル	役割
src/hooks/useAuth.tsx	UiPath SDKの認証コンテキスト。login/logout/isAuthenticated/sdk を提供。

• src/utils/-

ファイル	役割
src/utils/formatters.ts	ステータス色、所要時間、プロセス名、埋め込みタスクURLの整形関数。

• src/components/-

ファイル	役割
src/components/Header.tsx	ヘッダー表示とログアウト操作。
src/components/Navigation.tsx	タブ切替UI（Processes / Process Instances）。
src/components/LoginScreen.tsx	UiPath OAuthログイン画面。
src/components/ProcessList.tsx	プロセス一覧とダッシュボード統計表示。
src/components/ProcessInstances.tsx	インスタンス一覧/詳細の親コンテナ。取得、フィルタ、ページング、詳細取得を担当。
src/components/InstanceList.tsx	インスタンスカード一覧とページングUI。
src/components/InstanceDetails.tsx	選択インスタンスの詳細（タイムライン、タスク、変数、添付）表示。

機能追加／改修を入れる場合

機能追加・改修時に 触れる可能性が高いファイルを、目的別に以下のを整理しました。

改修したいこと（例）	触れる可能性があるファイル	何を直す/追加するか（典型例）
OAuth情報・接続先の変更（Org/Tenant/ClientID/Scope）	.env, .env.example	環境変数の追加/変更、スコープ調整、リダイレクトURI変更
ローカル開発のCORS/プロキシ調整	vite.config.ts	proxy のパス調整、Org名の差し替え、APIパス追加
起動コマンド/依存ライブラリ追加	package.json, package-lock.json	UI部品やユーティリティ追加、SDKバージョン更新、スクリプト追加
ESLint/TS設定の調整	eslint.config.js, tsconfig*.json	ルール変更、型チェックの厳格化、パスエイリアス追加
アプリの画面構成・認証による画面出し分け	src/App.tsx	ログイン後の表示分岐、画面追加、タブ増設、初期ロード処理
Reactエントリ/全体初期化（プロバイダ追加など）	src/main.tsx	Context Provider追加、初期化処理の差し込み
グローバルCSS・Tailwindの読み込み	src/index.css, tailwind.config.js, postcss.config.js	追加の共通スタイル、Tailwindスキャン対象変更（UI追加時）
認証（login/logout）やSDK初期化の挙動変更	src/hooks/useAuth.tsx	トークン保持/更新、ログイン失敗時の扱い、SDK初期化タイミング変更、ユーザー情報保持
ステータス表示・所要時間・URL生成など共通整形の追加	src/utils/formatters.ts	新しいステータス対応、表示文言統一、期間/時刻フォーマット追加、埋め込みURLの生成ロジック更新
ヘッダーに情報追加（ユーザー表示/環境表示など）	src/components/Header.tsx	ログインユーザー名表示、Org/Tenant表示、ログアウト導線
タブ追加・画面切り替えの拡張	src/components/Navigation.tsx, src/App.tsx	新しいタブ（例：Tasks/Settings）追加、表示条件（権限/ロール）
ログイン画面の説明や導線調整	src/components/LoginScreen.tsx	画面文言、ヘルプリンク、ログイン失敗時メッセージ追加
プロセス一覧の列追加・フィルタ/検索/ソート追加	src/components/ProcessList.tsx, src/utils/formatters.ts	一覧UI拡張、検索条件追加、表示項目追加、整形関数追加
ダッシュボード統計の追加/変更	src/components/ProcessList.tsx	KPI計算の追加、表示ロジック変更、集計対象ステータス追加
プロセスの起動（Start）に引数入力や確認を追加	src/components/ProcessList.tsx, src/hooks/useAuth.tsx	入力フォーム追加、起動API呼び出し拡張、SDK呼び出し時のパラメータ追加
インスタンス一覧のフィルタ・ページング改善	src/components/ProcessInstances.tsx, src/components/InstanceList.tsx	取得クエリ変更、ページングUI変更、フィルタ条件追加
インスタンス詳細（タイムライン/変数/タスク/添付）表示の拡張	src/components/InstanceDetails.tsx, src/utils/formatters.ts	表示セクション追加、データ整形、詳細API呼び出し結果の表示
インスタンス詳細の取得方法・更新頻度の調整	src/components/ProcessInstances.tsx	詳細取得タイミング、ポーリング間隔、再取得ボタン追加、エラーハンドリング
添付ファイル表示・扱いの拡張（ダウンロード等）	src/components/InstanceDetails.tsx	添付リスト表示、リンク/ダウンロード導線、ファイルメタ情報の見せ方
例外時の表示（エラー/空データ/権限不足）を改善	src/components/*（主に ProcessList.tsx, ProcessInstances.tsx, InstanceDetails.tsx）	エラーメッセージ、再試行ボタン、権限不足の案内、ローディング表示
faviconや基本HTMLの変更	index.html, src/assets/favicon.png	タイトル変更、メタ情報追加、アイコン差し替え
Viteテンプレ由来CSSの整理（必要なら）	src/App.css	不要なCSSの削除/最小化（UIに影響が出るなら調整）

UiPath Conversational Agent Appの解説

このサンプルは、UiPath Conversational Agents と連携する React + TypeScript アプリで、UI・認証・会話管理・ストリーミング処理が役割ごとに分離されています。

サンプルの構成（フォルダ・ファイル）

• ルート：

ファイル	役割
.env	ローカル実行用の環境変数（OAuth情報など実値）。
.env.example	.env のテンプレート。必要な VITE_UIPATH_* を定義。
index.html	SPAの土台HTML。#root に React をマウント。
package.json	依存関係、dev/build/lint/preview スクリプト定義。
package-lock.json	依存バージョン固定。
postcss.config.js	Tailwind + Autoprefixer のPostCSS設定。
README.md	セットアップ手順、OAuth設定、機能概要。
tailwind.config.js	Tailwind対象ファイルとチャット用カラートークン定義。
tsconfig.json	TypeScriptコンパイル設定（strict等）。
vite.config.ts	Vite設定。Reactプラグインとチャンク分割設定。

• src：

ファイル	役割
src/main.tsx	エントリポイント。App を描画。
src/App.tsx	認証状態に応じて LoginScreen / ChatLayout を切替。Provider構成の起点。
src/index.css	グローバルCSS、スクロールバー、Markdown表示スタイル。
src/types.ts	ChatMessage / tool call / interrupt / citation など共通型定義。
src/vite-env.d.ts	import.meta.env の型定義。
src/assets/favicon.png	ファビコン。

• src/context：

ファイル	役割
src/context/AuthContext.tsx	UiPath SDK認証（初期化、ログイン、ログアウト、状態保持）。
src/context/ConversationalAgentContext.tsx	会話アプリ全体のオーケストレーション層。hooksを束ねてUIに提供。
src/context/ConversationalAgentContext - コピー.tsx	ConversationalAgentContext.tsx のコピー（バックアップ用途と思われる重複ファイル）。

• src/hooks：

ファイル	役割
src/hooks/useAgents.ts	エージェント一覧取得と選択状態管理。
src/hooks/useConversations.ts	会話一覧CRUD、ページング、ラベル更新管理。
src/hooks/useChat.ts	メッセージ送受信、セッション、ストリーミング、履歴、フィードバック、割り込み処理。

• src/components：

ファイル	役割
src/components/ChatLayout.tsx	レイアウト本体。エラー表示、Sidebar、ChatAreaを配置。
src/components/Sidebar.tsx	会話一覧、作成/削除/改名、接続状態、折りたたみUI。
src/components/AgentSelector.tsx	利用エージェントの選択ドロップダウン。
src/components/ChatArea.tsx	メッセージ表示領域と入力欄を統合。履歴追加読み込みも担当。
src/components/ChatInput.tsx	メッセージ入力、添付ファイル追加、送信処理。
src/components/MessageBubble.tsx	各メッセージ表示。Markdown/HTML/LaTeX、引用、ツール呼び出し、割り込みUI。
src/components/WelcomeScreen.tsx	会話未開始時の初期画面とサジェスト表示。
src/components/LoginScreen.tsx	OAuthログイン画面。
src/components/Spinner.tsx	共通ローディングスピナー。
src/components/ErrorBoundary.tsx	レンダリング例外を捕捉してフォールバックUI表示。

Conversational Agent アプリの全体フロー

以下が、Conversational Agent アプリの全体フローをまとめた Mermaid 図です。

Conversational Agent アプリが「起動〜会話開始〜ストリーミング受信」まで動くときの呼び出し

以下は、この Conversational Agent アプリが「起動〜会話開始〜ストリーミング受信」まで動くときの呼び出し順です。

1) アプリ起動〜画面表示まで（最初に必ず通る）

• src/main.tsx

  • React のエントリポイント
  • App を #root にマウント（多くの場合ここで Provider も差し込み）

• src/App.tsx

  • アプリ全体の起点
  • 認証状態を見て以下を出し分ける
    • 未ログイン → LoginScreen
    • ログイン済み → ChatLayout

• src/context/AuthContext.tsx

  • App から参照される（または main.tsx / App.tsx で Provider として使われる）
  • UiPath SDK の初期化、login/logout/isAuthenticated などの状態を提供

2) ログイン〜SDK初期化まで（未ログインの場合）

• src/components/LoginScreen.tsx

  • 「Sign in with UiPath」などのログイン UI

• src/context/AuthContext.tsx（login 実行）

  • OAuth 認証開始 → 認証完了後にアプリへ戻る
  • トークンや認証状態を保持し、UiPath SDK を初期化

• src/App.tsx（再レンダリング）

  • isAuthenticated が true になり、ChatLayout 側へ切替

3) チャット画面表示〜初期データロード（ログイン済みの場合）

• src/components/ChatLayout.tsx

  • レイアウト本体（Sidebar / ChatArea を配置）
  • 例外保護として ErrorBoundary を噛ませることが多い

• src/context/ConversationalAgentContext.tsx

  • “会話アプリの司令塔（オーケストレーション層）”
  • 内部で主に以下の hooks を束ねて UI に渡す：
    • useAgents（エージェント一覧）
    • useConversations（会話一覧）
    • useChat（送受信・ストリーミング）

• src/hooks/useAgents.ts（初期ロード）

  • 利用可能な Agent の一覧取得
  • 選択中 Agent の状態管理

• src/hooks/useConversations.ts（初期ロード）

  • 会話一覧の取得（ページング含む）
  • 新規作成 / リネーム / 削除などの CRUD

• src/components/Sidebar.tsx

  • 会話一覧を表示し、会話選択・作成・削除などを操作

• src/components/ChatArea.tsx

  • 選択中の会話のメッセージ表示＋入力欄（ChatInput）をまとめる

4) メッセージ送信〜ストリーミング受信（会話の本体）

• src/components/ChatInput.tsx

  • テキスト入力、ファイル添付、送信ボタン

• src/hooks/useChat.ts（send 実行）

  • メッセージ送信処理の中心
  • ここで多くの場合：
    • 会話IDの決定（新規なら作成）
    • メッセージをローカル state に追加（楽観表示）
    • WebSocket 接続開始 or 既存接続利用
    • ストリーミング受信を開始

• WebSocket ストリーミング（useChat.ts）

  • 応答がチャンクで届くたびに state 更新
  • 接続状態監視 / エラー処理もここが担当になりがち

• src/components/MessageBubble.tsx（レンダリング）

  • state 更新に伴って逐次描画
  • Markdown / HTML / 画像 / 引用（Citations）を表示
  • ツール呼び出し可視化、割り込み（Interrupt）UI もここで表示されることが多い

• (必要に応じて)src/hooks/useConversations.ts

  • 会話ラベルの自動更新（最初の発話からタイトル生成など）
  • 会話履歴の追加ロード（ページング）

5) ツール呼び出し・割り込み・フィードバック

• ツール呼び出し可視化

  • useChat.ts が tool call 情報を受け取り state 更新
  • MessageBubble.tsx が tool 名 / input / output を描画

• 割り込み（確認プロンプト）

  • useChat.ts が “確認待ち状態” を保持
  • MessageBubble.tsx が「続行/キャンセル」などの UI を表示

• フィードバック（👍/👎）

  • useChat.ts が feedback 送信 API を呼ぶ
  • UI 側は message / exchange 単位で状態反映

最後に

本記事では、UiPath公式の TypeScript サンプル（Maestro / Conversational Agent）を動かし、設定手順と全体構造のポイントを整理しました。
サンプルを起点にすることで、認証やSDK連携をゼロから組む手間を省きつつ、実務アプリの土台を短時間で用意できます。