方法: UiPath エージェントをデプロイする

このページでは、 ローコード UiPath エージェント のライフサイクル全体を CLI から順を追って説明します。すなわち、ローコード エージェントをディスク上でスキャフォールディングし、検証、パッケージ化、パブリッシュして Orchestrator にデプロイし、ジョブとして実行できる状態にします。このツールでは、 (Python ベースのコード化されたエージェント)uip agentuip codedagent とは異なる ツールを使用します。

デプロイに既に慣れている場合は、Agents uip solutionソリューション ラッパーなしでデプロイできる点について知っておくことが重要です。uip agent publish コマンドは、独自のパックを実行して solution-pack →→アップロード パイプラインを内部→移行し、uip agent deploy結果を直接インストールします。単一エージェント プロジェクトの .uipx ソリューション マニフェストを作成する必要はありません。

ライフサイクル

init → validate → pack → publish → deploy → run

各動詞は、次の動詞が消費するものを生成します。

動詞	入力	出力	ログインが必要です。
init	ターゲット ディレクトリ	agent.json + プロジェクトツリー	いいえ
validate	プロジェクト ディレクトリ	ディスク上の移行されたファイル	いいえ
pack	プロジェクト ディレクトリ	.uis アーカイブ	いいえ
publish	プロジェクト ディレクトリ またはプロジェクト .uis	PackageVersionKey Orchestrator で	はい
deploy	PackageVersionKey	デプロイされたフォルダー + リリース	はい

ローカル動詞(init、 validate、 pack)はアクティブなセッションを必要とせず、どのビルドステージでも実行できます。Orchestrator に書き込むものはすべて、最初に uip login する必要があります。

1.足場

uip agent initを使用して新しいエージェント プロジェクトを作成します。

uip agent init ./invoice-agent \
  --model gpt-4o-2024-11-20 \
  --system-prompt "You are an invoice triage agent."

これにより、完全なスタンドアロン プロジェクト ツリーが書き込まれます。

invoice-agent/
  agent.json
  project.uiproj
  entry-points.json
  flow-layout.json
  evals/
    evaluators/<semantic>.json
    evaluators/<trajectory>.json
    eval-sets/evaluation-set-default.json
  features/
  resources/

ディレクトリ名がエージェント名になります。 [a-zA-Z0-9_ -]+と一致する必要があります。空でないディレクトリを上書きするには、[ --force を渡します。

Maestro フロー内に存在するエージェントの場合は、代わりに --inline-in-flow を使用します。 agent.json と flow-layout.jsonのみを含む UUID という名前のサブフォルダーが生成されます。 詳しくは、init --inline-in-flowをご覧ください。

2. オーサリングリソース

実際のエージェントには通常、3種類のリソースが必要です。agent.jsonを直接編集するか、構造化された編集コマンドを使用します。

• 入力と出力 — スキーマ パラメーターの uip agent input add / uip agent output add。
• ツール — Integration Service のコネクタ、Orchestrator プロセス、その他のエージェント、API ワークフロー、プロセス オーケストレーション フロー、IXP スキル uip agent tool add。
• コンテキスト — RAG インデックスのバインディングに uip agent context add。
• エスカレーション — 人間参加型のハンドオフ uip agent escalation add。

# Add an input parameter
uip agent input add invoicePath --type string \
  --description "Path to the invoice PDF"

# Add an output parameter
uip agent output add verdict --type string

# Add a RAG context bound to an index
uip agent context add invoiceKnowledge --index invoices-kb

# Add a Slack integration tool
uip agent tool add notify --type integration \
  --connector uipath-slack --object-name message

完全なフラグセットについては、それぞれのリファレンスページを参照してください。すべての編集で agent.json と entry-points.json の同期が保たれます。

3. 検証する

agent.jsonに手動で編集した後、または構造化された編集を行った後、uip agent validateを実行します。

uip agent validate ./invoice-agent

Validate は ローカル専用 (ログイン不要) で、静的チェック パスとスキーマ移行パイプラインを実行します。成功すると、移行されたファイルの内容がディスクに書き戻され .agent-builder/ スキャフォールディングが再生成されます。失敗した場合は、ファイルパスと終了コード 1 を含むエラーのリストを取得しますが、何も書き込まれません。

パブリッシュステップの前にゲートとしてCIでこれを実行します。これにより、パブリッシュに時間がかかるエラーのクラス (モデルが無効、 messages[].contentTokensの破損、スキーマに required エントリが見つからない) をキャッチします。

4.パック(オプション)

uip agent pack は、プロジェクトを .uis アーカイブにバンドルします。これは、次の場合にのみ必要です。

• 成果物を手作業で検査またはアーカイブする必要がある。
• 対話型編集のために、uip agent push を使用して Studio Web にプッシュする予定です。
• パイプラインでは、個別のビルド エージェントとデプロイ エージェントを使用し、それらの間で 1 つのファイルを渡す必要があります。

uip agent pack ./invoice-agent -d ./dist
# → ./dist/invoice-agent.uis

publish は独自の内部パック パイプラインを実行するため、単純な「ビルドとデプロイ」のフローでは、 この手順を完全にスキップ して、プロジェクト ディレクトリを publish に直接渡すことができます。

5. Orchestrator にパブリッシュする

uip agent publish プロジェクトをパッケージ化して予期されるstorageVersionに移行し、ソリューション ドキュメントを .zipして、テナントのソリューション フィードにアップロードします。uip loginが必要です。

uip agent publish ./invoice-agent --package-version 1.0.0

出力:

{
  "Code": "AgentPublish",
  "Data": {
    "Status": "Published successfully",
    "Name": "invoice-agent",
    "Version": "1.0.0",
    "PackageVersionKey": "a1b2c3d4-0000-0000-0000-000000000050"
  }
}

PackageVersionKeyはdeploy消費するものです。スクリプトでキャプチャします。

PVK=$(uip agent publish ./invoice-agent \
  --package-version 1.0.0 \
  --output-filter "Data.PackageVersionKey" \
  --output plain)

--direct を使用する場合

既定では、ソリューション API を介して publish がアップロードされます。--direct フラグはソリューションをバイパスし、各.nupkg Orchestrator のパッケージ フィードに直接アップロードして、パッケージごとにReleaseを作成します。これは、次の場合に使用します。

• プラットフォームの理由によりソリューションのデプロイ パスが失敗しているため、ブロックを解除する必要があります。
• 特定のフォルダーにリリースをすぐに作成する必要がある (パス --folder-id)。

--directモードでは、応答にはPackageVersionKeyがありません。これに相当するのは、 Releases[]のリリースごとのKeyであり、uip agent run startで直接使用できます。

6. デプロイ

uip agent deploy は、パブリッシュされたパッケージを Orchestrator フォルダーにインストールしてアクティベーションします。ソリューションの完全なデプロイ パイプライン (設定→デプロイ→インストール→プロビジョニング→アクティブ化) を推進し、各フェーズをターミナルにポーリングします。

uip agent deploy "$PVK" --name invoice-agent

--folder-keyを指定しない場合、deploy はフォルダー (--nameによる名前) を自動作成し、次の操作も行います。

1. テナントレベルのサーバーレス マシン テンプレートをフォルダーに割り当てます。
2. 割り当て可能なユーザーにフォルダーに対する Automation User ロールを付与します。

プロビジョニングの失敗は警告として表示され、デプロイは成功します。その後、マシンとユーザーを手動で割り当てます。

既存のフォルダーにデプロイするには、以下の手順を実行します。

uip agent deploy "$PVK" --folder-key <folder-guid> --name invoice-agent

フォルダー キーをuip or folders list --allで検索します。

インストール専用および強制アクティブ化

• --skip-activate インストール後に停止します。エージェントをトラフィックに解放する前に Orchestrator でデプロイを確認する場合に便利です。後で uip solution deploy activate に電話して完了します。
• --force-activate 、同じ構成キーにある既存のデプロイに対して再アクティブ化されます。これを使用すると、最初にアンインストールせずに、実行中のデプロイを新しいバージョンに置き換えることができます。

タイムアウト時の動作

--timeout (既定値は 120 秒) によって、各ポーリング フェーズが境界になります。タイムアウト時に deploy が終了します 2 — Orchestrator は引き続きバックグラウンドでデプロイを完了する可能性があります。より長いタイムアウト値で再実行するか、Orchestrator の UI でステータスを確認します。deployで2終了コードは、uip tm waitと同様に、認証エラースロットのドメイン固有の再利用です(deploy終了コードを参照してください)。

ソリューションのデプロイとの対比

エージェントは、他のプロジェクト (ワークフロー、テスト ケース) と一緒に .uipx ソリューション内でリリースできますが、エージェントが単一エージェントのプロジェクトの場合は、ダイレクト パスの方が短くシンプルです。

シングルエージェント	マルチプロジェクト ソリューション
uip agent publish ./my-agent --package-version 1.0.0	uip solution pack ./my-solution ./dist --version 1.0.0
uip agent deploy <PackageVersionKey>	uip solution publish ./dist/my-solution.1.0.0.zip Then uip solution deploy run …
フォルダーの自動作成 + プロビジョニング	--folder-nameごとに作成されるフォルダーdeploy config を使用したプロビジョニング
成果物 1 .uis	複数の.nupkgを含む 1 つの.zip

エージェントがスタンドアロン ユニットの場合は、エージェント パスを選択します。リソースを共有する RPA ワークフロー、ライブラリ、またはテスト ケースと共にエージェントを出荷する必要がある場合は、ソリューション パスを選択します。 詳しくは、uip solutionをご覧ください。

パイプライン対応の完全なスクリプト

#!/usr/bin/env bash
set -euo pipefail

AGENT_DIR="./invoice-agent"
VERSION="${AGENT_VERSION:-1.0.0}"

# 1. Auth (External App in CI)
uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT"

# 2. Validate locally — fail fast before uploading
uip agent validate "$AGENT_DIR"

# 3. Publish
PVK=$(uip agent publish "$AGENT_DIR" \
  --package-version "$VERSION" \
  --output-filter "Data.PackageVersionKey" \
  --output plain)

# 4. Deploy
uip agent deploy "$PVK" \
  --name "invoice-agent-${ENVIRONMENT}" \
  --timeout 300

その後、uip agent run start でジョブを開始するか、評価の実行 ( uip agent eval run start ) を実行して、デプロイがグリーンと見なされる前に、評価セットに対して動作を検証します。

参照

• uip agentの概要 — エージェント ツール内のすべての動詞。
• uip solutionの概要 — 複数プロジェクト プロジェクトのためのソリューションベースのデプロイ。
• uip or jobs — エージェントの実行の基盤となるジョブ モデルです。
• 認証 — セッション、テナント、 env. プレフィックス。
• 方法: CI から Orchestrator にデプロイ する — CI 固有の認証、キャッシュ、バージョンのピン留め。