Hugging Face の外部 LLM を安全につなぐ UiPath Coded Agent 入門
この記事では、UiPath Coded Agent から Hugging Face のモデルを呼び出すシンプルな実装例を紹介します。
UiPath Coded Agent は、Python などのコードでエージェントの処理を実装できる UiPath のエージェント開発方法です。
UI 上で設定を組み合わせてエージェントを作成する UiPath Agent Builder に対して、Coded Agent は外部 API、外部 SDK、独自の処理フロー、エラー処理などをコードで細かく制御したい場合に向いています。
この記事のポイントは、Hugging Face の API トークンをコードに直接書かず、UiPath Orchestrator の Asset に保存して Coded Agent から取得することです。
外部 LLM を試すときに、API キー管理と実装の見通しを分けられるため、学習用にも実務検証用にも扱いやすい構成になります。
この記事は、公開情報とサンプル実装に基づく教育目的の内容です。個人情報、テナント名、社内限定情報、非公開情報は含めません。
想定読者
- Hugging Face の外部 LLM を UiPath から安全に呼び出す流れを知りたい方
- UiPath Coded Agent で外部 API や Python SDK を扱う基本的な考え方を知りたい方
- API トークンをコードに直接書かず、Orchestrator Asset から取得する構成を理解したい方
Hugging Face とは
Hugging Face は、機械学習モデル、データセット、デモアプリなどを共有・利用できるプラットフォームです。
Hugging Face Hub には、さまざまなタスク向けのモデルがリポジトリとして公開されています。
代表的なモデルの種類は次のようなものです。
| 分類 | 例 |
|---|---|
| 自然言語処理 | Text Generation、Summarization、Translation、Question Answering、Text Classification |
| マルチモーダル | Image-Text-to-Text、Document Question Answering、Visual Question Answering |
| Computer Vision | Image Classification、Object Detection、Image Segmentation、Text-to-Image |
| Audio | Automatic Speech Recognition、Text-to-Speech、Audio Classification |
| Tabular / その他 | Tabular Classification、Tabular Regression、Reinforcement Learning |
モデルを使う前には、必ず Model Card を確認します。
Model Card には、モデルの概要、想定用途、制限事項、学習データ、評価結果、ライセンスなどが記載されています。
公開・業務利用の前には、ライセンス、データの扱い、利用条件を確認してください。
今回のサンプルでは、Hugging Face の Inference Providers 経由で、Text Generation / Chat Completion 系のモデルを呼び出します。
UiPath Coded Agent とは
UiPath Coded Agent は、Python などのコードを使ってエージェントの処理を実装する方法です。
Coded Agent では、入力を受け取り、必要な処理をコードで実行し、結果を出力として返します。
そのため、外部 API 呼び出し、外部 SDK の利用、複数ステップの処理分岐、例外処理、レスポンス整形などを明示的に制御できます。
この記事では、以降 Coded Agent と記載する場合、UiPath Coded Agent を指します。
UiPath Agent Builder と Coded Agent の違い
UiPath でエージェントを作成する方法として、代表的には UiPath Agent Builder と Coded Agent があります。
Agent Builder は、Studio Web 上でプロンプト、ツール、コンテキスト、エスカレーションなどを UI で構成できるため、ローコードでエージェントを作成したい場合に向いています。
一方で、Coded Agent は Python などのコードで処理を実装するため、より細かい制御が必要なケースに向いています。
なぜ UiPath Coded Agent なのか
UiPath Agents には、Studio Web でフォームやキャンバスを使って構成する方法と、Python などのコードで実装する Coded Agent があります。
Studio Web の Agent Builder は、プロンプト、ツール、コンテキスト、エスカレーションなどを UI で構成できるため、最初のエージェントを作るにはとても始めやすい選択肢です。
一方で、このサンプルのように次のことを明示的に制御したい場合は、Coded Agent が自然です。
| やりたいこと | Coded Agent が向いている理由 |
|---|---|
| 外部 Python SDK を使う |
huggingface_hub などの Python ライブラリを直接使える |
| 外部 LLM API を呼び出す | API 呼び出し、プロバイダー指定、エラー処理をコードで管理できる |
| API キーを安全に扱う | Orchestrator Asset から実行時に取得する処理を書ける |
| 実行フローを分けたい | LangGraph で prepare -> call model -> format のように処理を分割できる |
| UiPath の運用に載せたい | Orchestrator のプロセスとして実行・管理しやすい |
つまり、Low-code Agent Builder は「UiPath が用意する UI と設定で素早く作る」選択肢、Coded Agent は「Python コードで外部システム連携や制御を細かく書く」選択肢として考えると理解しやすいです。
今回のゴールは、Coded Agent の強みを見せるために、あえて外部 LLM API と Orchestrator Asset を組み合わせています。
全体構成
このサンプルの処理フローは次の通りです。
このサンプルの処理フローは次の通りです。
- Coded Agent が入力メッセージを受け取る
- Hugging Face に渡す messages を作成する
- Orchestrator Asset から Hugging Face の API トークンを取得する
- Hugging Face Inference Provider にリクエストを送る
- モデルの応答を UiPath の Output 形式に整えて返す
LLM を実際に呼び出しているのは call_huggingface_model ノードです。ここで Hugging Face の API トークンを Orchestrator Asset から取得し、Hugging Face Inference Provider にリクエストを送ります。
サンプルコードの構成
主なファイルは次の通りです。
| ファイル | 役割 |
|---|---|
settings.py |
既定の Hugging Face モデル、Provider、Asset 名を定義 |
models.py |
Coded Agent の Input / State / Output スキーマ |
credentials.py |
Orchestrator Asset またはローカル環境変数からトークンを取得 |
llm_clients.py |
huggingface_hub.InferenceClient の薄いラッパー |
process.py |
リクエスト準備、外部 LLM 呼び出し、レスポンス整形 |
graph.py |
LangGraph のノード定義 |
モデルと Provider の指定
settings.py では、既定のモデルと Provider を分けて定義しています。
DEFAULT_MODEL = "cyberagent/DeepSeek-R1-Distill-Qwen-14B-Japanese"
DEFAULT_PROVIDER = "featherless-ai"
HUGGINGFACE_ASSET_NAME = "HuggingFace_Token"
HUGGINGFACE_TOKEN_ENV_VAR = "HF_TOKEN"
HUGGINGFACE_TIMEOUT_SECONDS = 60.0
Hugging Face では、モデル ID と Inference Provider を分けて考えると理解しやすいです。モデル ID は Hugging Face Hub 上のモデル名、Provider は実際に推論を実行するサービスです。
Input / Output
この Agent は、ユーザーからのメッセージ、モデル ID、Provider 名を受け取ります。
class Input(BaseModel):
message: str
model: str = DEFAULT_MODEL
provider: str = DEFAULT_PROVIDER
出力には、実行成功可否、利用したモデル、Provider、トークン取得元、モデル応答、エラー内容を含めています。
class Output(BaseModel):
success: bool
model: str
provider: str
token_source: str
response_message: str
error_message: str = ""
API キーは Orchestrator Asset に保存する
外部 API キーをコードに直接書くのは避けます。このサンプルでは、まず Orchestrator Asset から HuggingFace_Token を取得します。
client = UiPath()
token = client.assets.retrieve_credential(name="HuggingFace_Token")
ローカル開発時だけ、環境変数 HF_TOKEN をフォールバックとして使えるようにしています。本番運用では、Asset または組織のルールに沿った資格情報管理を使うのがおすすめです。
Hugging Face を呼び出す部分
Hugging Face への呼び出しは huggingface_hub.InferenceClient を使います。
client = InferenceClient(
api_key=token,
provider=provider,
timeout=60.0,
)
completion = client.chat.completions.create(
model=model,
messages=messages,
)
この部分は Low-code の設定だけではなく、Python の SDK と例外処理を直接扱いたい箇所です。ここが Coded Agent を選ぶ理由になります。
たとえば、次のような制御をコードで書くことができます。
- 利用するモデルを入力値で切り替える
- Provider を指定する
- タイムアウトを設定する
- API エラー時のメッセージを整える
- トークンの取得元を出力に含める
このような実装の自由度が、Coded Agent を選ぶ理由になります。
LangGraph の流れ
graph.py では、処理を 3 つのノードに分けています。
| ノード | 役割 |
|---|---|
prepare_request |
入力を整え、モデルに渡す messages を作る |
call_huggingface_model |
Orchestrator Asset からトークンを取得し、Hugging Face を呼び出す |
format_response |
UiPath に返す Output 形式に整える |
画面キャプチャを入れる場合は、call_huggingface_model が外部 LLM API を呼び出すノードであることが分かる画像を入れると、読者が理解しやすくなります。
実行例
入力例です。
{
"message": "UiPath Coded Agent を使うメリットを日本語で3つ教えてください。",
"model": "cyberagent/DeepSeek-R1-Distill-Qwen-14B-Japanese",
"provider": "featherless-ai"
}
出力例です。
{
"success": true,
"model": "cyberagent/DeepSeek-R1-Distill-Qwen-14B-Japanese",
"provider": "featherless-ai",
"token_source": "orchestrator_asset",
"response_message": "....",
"error_message": ""
}
まとめ
UiPath Coded Agent は、Python で外部 API や外部 SDK を制御しながら、UiPath の実行・管理基盤に載せたい場合に有効です。
今回のサンプルでは、Hugging Face の外部 LLM を呼び出しつつ、API トークンは Orchestrator Asset で管理しました。
Agent Builder だけで完結するケースでは、UI ベースで素早くエージェントを作れる点が便利です。
一方で、外部 LLM、独自 SDK、細かい例外処理、モデル選択ロジックを扱う場合は、Coded Agent の方が実装意図を明確に表現しやすくなります。
外部 LLM を UiPath から安全に呼び出す構成を検証したい場合、Coded Agent と Orchestrator Asset の組み合わせは分かりやすい出発点になります。