uipath-functions

UiPath コード化関数

ビジネスロジックを担う、アトミックで決定論的な単位です。LLM による推論やエージェントループはなく、Python または TypeScript/JavaScript で記述し、UiPath のファーストクラスの成果物として提供されます。どちらの言語でも、1 つの uip function CLI を使用します。コード化関数は、型付きの入力を受け取り、決定論的なコードを実行して、型付きの出力を返します。汎用アクティビティでは必要なロジックをカバーできない場合（カスタム認証を使った API 呼び出し、ドメインルール、Integration Service 経由の ERP クエリ、データ変換など）に使用してください。

このスキルを使用する場面

• どちらかの言語でコード化関数をひな形から作成、記述、または変更する（uip function new <NAME> -l py|ts|js）
• 型付きの契約を宣言する — Pydantic の Input/Output（Python）、または defineSchema<T>() / JSON Schema リテラル（JS/TS）
• ローカルでテストする：uip function run（両言語）、uip function serve と curl（JS/TS の HTTP エンドポイント）
• エラー処理：返されるエラーフィールド（Python）、FunctionError / ステータスコードとジョブの障害時の動作（JS/TS）
• 関数内から UiPath プラットフォーム API を呼び出す（Python SDK、ctx トークンを使用する @uipath/uipath-typescript）
• コード化アプリのフロントエンドを JS/TS 関数のバックエンドに接続する（トークン、CORS、タイムアウト予算、ローカル開発ループ）
• パッケージ化、本番環境への公開と呼び出し、ソリューションへの登録、SDK 呼び出しからの bindings.json リソースバインディングの導出
• デプロイ後の障害をデバッグする：コールドスタートのハング、エラーコード 4801/4804/1623、トークンの不足、エントリーポイントのエラー

次の用途には、このスキルを使用しないでください。

• LLM/エージェント型のプロジェクト（agent.json、LangGraph、LlamaIndex、OpenAI Agents、エージェントループ）→ uipath-agents
• コード化アプリのフロントエンドそのもの（React/Vite アプリのコード、PKCE のセットアップ、アプリのデプロイ）→ uipath-coded-apps

言語の選択

何かを行う前に、既存プロジェクトのシグナルを確認してください。新規プロジェクトの場合、言語は呼び出し元のスタックに合わせます。

	Python	JS/TS
ひな形の作成	uip function new <NAME> -l py（-l py は必須）	uip function new <NAME> -l ts / -l js（CLI のデフォルトは ts）
プロジェクトのシグナル	pyproject.toml と uipath.json の functions マップ	package.json と uipath.json の functions マップ
契約	Pydantic の BaseModel / @dataclass Input/Output	defineSchema<T>()（TS） / JSON Schema リテラル（JS）
エントリーポイント	uip function init によって生成される "main": "main.py:<fn>"	functions/<FILE>.ts:default、自動同期される。init は不要
呼び出しモード	ジョブとして実行（Maestro、エージェント、Orchestrator API）	宣言するモードは 1 つ：HTTP エンドポイントまたはジョブとして実行。両方は不可
ローカル開発	uip function run	uip function serve（:7070 で HTTP） / uip function run（単発ジョブ）
参照資料	references/python/	references/js/

ジョブ開始可能な関数は、Maestro BPMN/Flow（Service Task）、コード化エージェント（ツールまたはステップとして）、他の関数、Orchestrator API（POST /Jobs/StartJobs）、またはスケジュールやトリガーから呼び出されます。一方、JS/TS の HTTP モード関数は、Orchestrator の HTTP トリガーを通じて同期的に呼び出されます（references/js/http-semantics-guide.md）。

重要なルール

両言語共通

1. コード化関数内で LLM を呼び出さないでください。 LLM による推論は決定論的な契約を損ないます。そのプロジェクトはエージェントです → uipath-agents。
2. uipath.json の functions マップは、プロジェクトがコード化関数であることを示します — これはすべてのツールが読み取る識別子です。
3. クラウドを利用する処理には認証が必要です：uip login --organization "<ORG>" --tenant "<TENANT>" --output json。

Python

1. UiPath() はモジュールレベルで絶対にインスタンス化しないでください — ゲッター内に遅延シングルトンを用意します。
2. エラーは送出せず、返します：出力フィールド error_type／error_message に値を設定し、エントリーポイントから例外を外部へ伝播させないでください。
3. uip function init は pack または push の前に実行する必要があります — entry-points.json と project.uiproj を生成し、ファイルが存在しない場合は bindings.json を空のひな型として作成します。スキーマまたはエントリーポイントを変更した後は、再実行してください。コードからバインディングが導出されることはありません（ルール 7）。
4. 型付き I/O は必須です — Pydantic BaseModel、pydantic.dataclasses.dataclass、標準ライブラリの @dataclass、または薄い型付きクラスを使用します。LLM Ops Traces のため、エントリーポイントに @traced(name=..., run_type="uipath") を適用します。
5. pyproject.toml には authors が必要です（ない場合、pack は Project authors cannot be empty として拒否します）。また、[build-system] セクションは指定しないでください。
6. uip function new -l py は関数のひな型を生成します — venv にインストールされているエージェントフレームワークのパッケージ（uipath-langchain、uipath-llamaindex、uipath-openai-agents）にかかわらず、functions マップを含む uipath.json を生成し、langgraph.json は生成しません。
7. バインディングは uipath SDK の呼び出しから導出します — 空のままにせず、推測もしないでください。 init の実行後は "resources": [] になります。sdk().assets／queues／processes／buckets／context_grounding／connections／mcp／tasks の呼び出しにはそれぞれ、references/python/bindings-reference.md の同期ワークフローで作成した、対応する bindings.json のエントリーが必要です。これがない場合、プロジェクトのパックと公開は正常に完了しますが、デプロイ時のマッピング対象となるリソースが表示されず、実行時に失敗します。uip function push は uip codedagent push と同様に、Resource Catalog に照らしてエントリーを解決します。

JS/TS

1. Error ではなく、必ず FunctionError をスローしてください。 通常のスローは、常に汎用的な 500（JsCodedFunction.HandlerError）になり、生のスタックが漏えいします。FunctionError(message, status) では、作成者が制御するステータスを指定できます（オプションに errorCode を渡すと、ジョブのエラーコードを設定できます）。引数の順序は (message, status) です。エラー処理を参照してください。
2. コントラクトはスキーマファーストです。 インターフェース（TS。ビルド時に変換されます）には defineSchema<T>() を、JS には JSON Schema リテラルをそのまま使用してください。新しい関数では zod／arktype／valibot を使用しないでください。静的なコントラクト抽出ができなくなり、ランタイム依存関係も追加されます。$ref、any、bigint、タプルは使用できません。スキーマリテラルは静的である必要があります。
3. 各ファイルには、functions/ の直下に defineFunction を 1 つだけデフォルトエクスポートしてください。 ヘルパーモジュールには _ プレフィックスを付けます（functions/_helpers.ts）。method と path は両方指定するか、どちらも指定しないでください。この組み合わせで関数の呼び出しモードが決まり、HTTP エンドポイントか通常のジョブ実行のいずれかになります。両方のインターフェイスで必要なロジックは、_ ヘルパーを共有する 2 つの薄い関数にしてください。
4. プロジェクト内のインポートには .ts 拡張子を付けてください（./_helpers.ts）。拡張子を省略したインポートはローカル開発では解決されますが、本番環境のコールドスタート時にランタイム全体がハングし、ログも出力されません。
5. ランタイム依存関係は dependencies に指定し、公開 npm のみを使用してください。SDK は devDependencies に残してください。 コールドスタート時の本番環境では npm install --omit=dev が実行されます。devDependencies からのランタイムインポートやプライベートレジストリの使用は、関数のクラッシュやハングの原因になります。依存関係を変更したら、必ずロックファイルを再生成してください。古い package-lock.json があると、すべてのルートが errorCode 4801 で失敗します。
6. 処理は 20 秒未満で完了させてください。ゲートウェイは 25 秒でタイムアウトし、CORS のないポーリング URL への 303 を返します。 ブラウザーの呼び出し元は結果を永久に失い、リダイレクトを使ってサーバー側で結果を取得する方法も文書化されていません。すべての外部呼び出しで AbortSignal.timeout(...) を使用してください。時間のかかる処理はジョブ実行関数に移してください。
7. 本番環境への POST では、入力が空でも body: '{}' が必要です。 ゲートウェイは空のボディを 400 errorCode 4804 で拒否します（ローカルの serve では拒否されないため、この不具合は本番環境でのみ発生します）。
8. トークンが 2 つあれば、ID も 2 つあります。 ctx.user.accessToken は呼び出し元のトークン（委任されたトークンで、呼び出し元のフォルダー権限を使用します）です。ctx.robot.accessToken は関数自身のロボット ID（S2S。特権付きの読み取りを行います）です。ローカルの serve では ctx.robot は常に null です（Bearer トークンが送信されていない場合は ctx.user のみ使用できます）。その場合は process.env["UIPATH_ACCESS_TOKEN"] にフォールバックしてください。
9. プラットフォームの接続情報は ctx.platform から取得してください（baseUrl、orgId、tenantId、folderKey）。入力フィールドから取得してはいけません。呼び出し元が制御できる URL はリダイレクトのリスクになります。環境変数（UIPATH_BASE_URL、UIPATH_ORG_ID、UIPATH_TENANT_ID）は、ローカル環境でのみ使うフォールバックです。
10. Orchestrator のジョブログに記録されるのは、SDK の logger.* のみです。 console.* はローカルに出力され、転送されません。
11. Buffer は使用しないでください。 Uint8Array、TextEncoder、TextDecoder を使用してください。
12. uip function publish の実行後、Orchestrator（Automations → Processes）で Function Release を手動で更新してください。 トリガーが新しいバージョンに同期されるのは、リリースの更新後のみです。
13. uip function run は HTTP 呼び出しではなく、1 回限りのジョブ実行です。 HTTP インターフェイスをローカルで試すには、serve サーバーに対して curl／fetch を実行してください。CLI のサブコマンドでルートを呼び出すことはできません。

クイックスタート

Python

uip function new <NAME> -l py    # scaffold a Python function project
# author: Pydantic Input/Output + @traced entrypoint, lazy UiPath() singleton, errors returned not raised
uip function init                # generate entry-points.json / project.uiproj; bindings.json starts empty
# sync bindings.json from the SDK resource calls — references/python/bindings-reference.md
uip function run <ENTRYPOINT> '{"document_id": "42"}'
uip function pack && uip function publish

スキーマ、テンプレート、uipath.json の登録、pyproject.toml、SDK の機能、添付ファイル、packOptions を含むワークフロー全体については、references/python/workflow-guide.md を参照してください。

JS/TS

uip function new <NAME> -l ts    # or -l js; --empty for no sample
# author: one default-exported defineFunction per functions/ file — method+path for HTTP, neither for run-as-job
uip function serve               # HTTP on :7070, hot reload; test with curl
uip function run --function <NAME> --input '{}'   # one-shot local job execution
uip function pack && uip function publish         # then update the Function Release in Orchestrator

// functions/invoice.ts
import { defineFunction, defineSchema, FunctionError } from "@uipath/coded-functions-js-sdk";

interface Input {
  invoiceId: string;
  /** @default 0 */
  amount?: number;
}
interface Output {
  approved: boolean;
}

export default defineFunction({
  name: "approve-invoice",
  method: "POST",
  path: "/invoice", // omit method+path entirely for a run-as-job function
  input: defineSchema<Input>(),
  output: defineSchema<Output>(),
  handler: async (input, ctx) => {
    if (!ctx.user?.accessToken) throw new FunctionError("Unauthorized", 401);
    return { approved: input.amount! < 10_000 }; // success data only — errors are thrown
  },
});

作成の詳細、ローカル開発、HTTP の仕様、デプロイ、バインディング、Coded App の接続については、references/js/ を参照してください（以下にナビゲーションがあります）。

CLI リファレンス

uip function new <NAME> -l py|ts|js [--empty]   # scaffold (TypeScript default; --empty is JS/TS only)
uip function init                    # Python only — entry-points.json, project.uiproj, empty bindings.json skeleton
uip function serve [--port 7070] [--runtime node|deno]   # JS/TS only — local HTTP server, hot reload
uip function run                     # both languages — one-shot local execution
uip function pack [--nolock]         # build the .nupkg
uip function publish [--feed-id <FEED_ID>]      # upload package to a process feed
uip function push --project-id <PROJECT_ID> [--ignore-resources]   # sync sources to Studio Web and import bindings.json resources
uip function runtime-install         # JS/TS — one-time runtime pre-install (otherwise downloaded on first serve/run)

廃止された複数形の表記（functions）は使用できません。必ず単数形の uip function と記述してください。

リファレンスのナビゲーション

知りたいこと	読む資料
Python：ワークフロー全体 — スキャフォールド、スキーマ、テンプレート、登録、依存関係、初期化、SDK 呼び出し、添付ファイル、パック	python/workflow-guide.md
Python：SDK のリソース呼び出しから bindings.json を導出して同期する — リソースごとのスキーマ、SubType、エントリーポイントのバインディング、push の動作	python/bindings-reference.md
JS/TS：ハンドラー、コントラクト、ctx、エラー、ログの作成	js/authoring-guide.md
JS/TS：ローカルでの実行とテスト（serve、run、env、トークン）	js/local-dev-guide.md
JS/TS：ルーティング、ステータスコード、デプロイ後の制限	js/http-semantics-guide.md
JS/TS：ジョブとして実行するモード、障害のセマンティクス	js/job-mode-guide.md
JS/TS：パック、公開、本番環境での呼び出し、ソリューション、コールドスタート	js/deployment-guide.md
JS/TS：バインディング — entry-points.json、bindings_v2.json、オーバーライド	js/bindings-guide.md
JS/TS：関数から UiPath API を呼び出す（uipath-typescript、IS）	js/calling-uipath-apis-guide.md
JS/TS：Coded App のフロントエンドを関数バックエンドに接続する	js/coded-app-wiring-guide.md

アンチパターン

Python

1. モジュールレベルで UiPath() をインスタンス化する — 常に getter 内の遅延シングルトンにしてください（Python Rule 1）。
2. エントリーポイントから例外を送出する — エラー出力フィールドに値を設定して、戻り値を返してください（Python Rule 2）。
3. スキーマ変更後に uip function init を実行しない — 古い entry-points.json が誤ったコントラクトとともに出荷されます（Python Rule 3）。
4. コードが SDK のリソースを呼び出しているのに、"resources": [] の bindings.json を出荷する — init が作成するのはスケルトンのみです。エントリーを導出してください（Python Rule 7）。

JS/TS

1. throw new Error("…") — 汎用的な 500 エラーになり、生のスタックが漏えいし、作成者がステータスを制御できません（JS Rule 1）。
2. 200 のレスポンス内で errors[] 配列を返す。 出力スキーマには成功データのみを含めます。関数が一度に送出するエラーは 1 つです。
3. 新しい関数で zod/arktype のコントラクトを使う — 静的抽出が機能しなくなり、ランタイム依存関係が追加されます（JS Rule 2）。
4. 拡張子なしの相対インポート — ローカルでは動作しますが、本番環境でのコールドスタートが停止します（JS Rule 4）。
5. ランタイム依存関係を devDependencies またはプライベートレジストリに追加する — コールドスタート時にスキップされるか、取得できません（JS Rule 5）。
6. 関数にアクセスするため、Coded App の Vite 設定に server.proxy を追加する — アプリの OAuth コールバックが壊れます。代わりに http://localhost:7070/<PATH> を直接 fetch してください（serve は CORS * を送信します）。
7. 関数の入力として baseUrl/orgId/tenantId を受け付ける — リダイレクトのリスクがあります。ctx.platform を使用してください（JS Rule 9）。
8. ブラウザーからポータルのドメインを呼び出す — そこでは CORS が使えません。ブラウザーからは api.<HOST> サブドメインを呼び出す必要があります。
9. 本番環境の診断に console.log を使う — ジョブログには出力されません（JS Rule 10）。
10. トリガー自身の Id から呼び出し URL を組み立てる — 404 errorCode 1623 が発生します。URL にはフォルダー Key GUID、パッケージ ID、スラッグを指定します。
11. 呼び出し元が 25 秒後に結果を取得できると想定する — HTTP 関数は 20 秒未満に保ち、それより長い処理はジョブとして実行する関数に移してください（JS Rule 6）。