render-workflows

Render Workflows

Render Workflows は、長時間実行される分散タスクをオーケストレーションするための SDK ベースの製品です。ワークフローサービスに Python または TypeScript の関数をタスクとして登録します。各タスクの実行は独立しており、後続の実行を連鎖させることができます。

ワークフロー、cron ジョブ、バックグラウンドワーカーのどれを選ぶべきかについては、references/service-types.md をお読みください。

Render SDK 1.x の API（Python の場合は render>=1.0.1、TypeScript の場合はバージョン 1.x の @renderinc/sdk）を使用してください。ローカルでの検証には Render CLI 2.12.0 以降が必要です。オプションのスキャフォールディングと CLI によるデプロイの完全なフローを使用する場合は、CLI 2.16.0 以降を使用してください。互換性のある最新リリースを優先してください。

Render Workflows とその SDK は、破壊的変更を導入する場合があります。既存のプロジェクトでは、インストール済みの SDK バージョンを正としてください。新しいプロジェクトでは、最新の公式ドキュメントとスターターテンプレートを使用してください。

最新の情報源を確認する

SDK コードを生成または変更する前に、インストール済みのバージョンを確認してください。

render --version
python -m pip show render
npm ls @renderinc/sdk

Render CLI がインストールされていない場合：

• macOS：brew install render
• Linux/macOS：curl -fsSL https://raw.githubusercontent.com/render-oss/cli/main/bin/install.sh | sh
• Windows：CLI リリースページから実行ファイルをダウンロードします

質問に合った情報源を使用してください。

• Python のシグネチャと最小バージョンについては、Python SDK リファレンス
• TypeScript のシグネチャと最小バージョンについては、TypeScript SDK リファレンス
• 最新のコマンドとフラグについては、Render CLI リファレンス
• タスクの動作と実行の連鎖については、ワークフロータスクの定義
• コンピュートプラン、クォータ、保持期間、料金については、Render Workflows の制限と料金
• 最新のスキャフォールディングパターンについては、Python の例およびTypeScript の例
• 実装と変更履歴については、Render SDK リポジトリ

タスクまたはクライアントのコードを生成する前に、関連する SDK の例を取得して、最新の API パターンを確認してください。

内容	Python	TypeScript
タスク定義（サブタスク、リトライ、ファンアウト）	example/task/main.py	examples/task/
クライアント（実行、開始、キャンセル、ストリーム、実行一覧の取得）	example/client/main.py	examples/client/
非同期クライアント	example/client/async_main.py	—

既存のプロジェクトの SDK メジャーバージョンを、明示せずにアップグレードしないでください。アップグレードが依頼に含まれている場合は、関連する SDK の変更履歴を読み、すべてのタスク定義と呼び出し元をまとめて移行してください。

SDK 1.x の不変条件

生成するコードでは、以下のルールを守ってください。

• Python では render パッケージをインストールしてインポートします。render_sdk ではありません。
• すべてのタスク関数は、最初の位置引数として TaskContext を受け取ります。これは Render が提供するもので、呼び出し側はタスク入力に含めません。
• タスクの実行を連鎖させるには、await ctx.run(task_definition, ...args) を使用します。タスク定義を直接呼び出すことはできません。
• ctx.run の連鎖に含まれるすべてのタスクは、同じワークフローサービスに属している必要があります。別のワークフローをトリガーする場合は、SDK クライアントまたは Render API を使用します。
• Python では、ワークフローのエントリーポイントから app.start() を呼び出します。TypeScript では、ワークフロー環境でのタスク登録時に自動的に開始されます。
• タスクの引数と戻り値は JSON シリアライズ可能である必要があります。

SDK コードを記述する際は、references/quick-reference.md をお読みください。連鎖、ファンアウト、再試行、スケジュール済みトリガー、ワークフロー間の呼び出しについては、references/task-patterns.md をお読みください。

開始方法を選ぶ

render workflows init の実行を必須にしないでください。既存のコードベースでは、SDK とタスク定義を直接追加し、プロジェクトの依存関係とビルドの規約を維持したうえで、ローカル開発サーバーを使って検証してください。最小限のプロジェクトや、直接統合する方法については、references/manual-scaffolding.md をお読みください。

オプションのスターター構成

ユーザーが手早く試せるサンプルプロジェクトや、新しいスタンドアロンのワークフローサービスを求めている場合は、CLI スキャフォルダーを使用します。

render workflows init

非対話型でセットアップする場合は、言語と配置先を明示します。

render workflows init --confirm --language python --dir workflows --git=false
render workflows init --confirm --language node --dir workflows --git=false

既存の Git リポジトリ内でスキャフォールディングを実行する際は、入れ子のリポジトリが作成されないように --git=false を使用します。ほかに便利なオプションとして、--template、--install-deps、--install-agent-skill があります。現在の動作は CLI リファレンスで確認してください。

SDK をローカルで試す

最初の統合では、実行可能な Python または TypeScript のローカル SDK チュートリアルに従ってください。ping を定義し、ローカルタスクサーバーを起動して、別のクライアントスクリプトから呼び出し、返された "pong" を確認します。このローカルの例では、init、デプロイ、Render API キーは不要です。ローカルモードは、タスクサーバーの環境だけでなく、呼び出し元のアプリケーションプロセスで設定してください。

SDK のタスク定義を追加または変更した後は、ローカル開発サーバーを主な検証手段として使用してください。ワークフローで実際に使う起動コマンドでサーバーを起動します。

render workflows dev -- <workflow-start-command>

別のターミナルで、ローカルサーバーに対してタスクを一覧表示し、実行します。

render workflows tasks list --local
render workflows start <task-name> --local --input='[]' -o json
render workflows tasks runs show <task-run-id> --local -o json

ローカルのタスク一覧にタスクが表示されない場合は、トラブルシューティング > ローカルのタスク一覧が空、またはタスクが表示されないを参照してください。

位置引数の入力には JSON 配列を使用します。Python のタスクには、名前付き入力として JSON オブジェクトを渡すこともできます。環境ファイル、カスタムポート、実行の確認、キャンセル、アプリケーションクライアントの設定については、references/local-development.md をお読みください。

非対話型モードでは、workflows start は実行が必ずしも完了する前に、新しいタスク実行 ID を返します。その ID を tasks runs show で使用し、実行が完了、失敗、またはキャンセルされるまで、上限を定めてポーリングしてください。実行が作成されたことだけでなく、結果またはエラーも確認してください。

安全かつ実用的な場合は、この検証を自分で実行し、終了後に開発サーバーを停止してください。ソースコードを確認しただけで、タスクが正常に登録されたと主張しないでください。

ローカルでの検証後にデプロイする

ワークフローを作成またはリリースすると、ユーザーの Render アカウントが変更されます。デプロイが依頼に含まれており、ローカル実行がサポートされている場合はローカルでタスクを検証してから実施してください。

デプロイの前、またはデプロイ状況を判断する前に、references/deployments.md を読み、ワークフロー固有のタスク登録動作も確認してください。

デプロイの前に認証し、対象のワークスペースを確認してください。

render whoami
render workspace current

認証情報がない場合は、対話型のローカルセッションには render login を使用するか、自動化には環境変数で RENDER_API_KEY を指定してください。キーを表示しないでください。

対象のブランチとリージョンを確認し、デプロイするコードそのものが GitHub、GitLab、または Bitbucket にコミットされ、プッシュされていることを確認してください。どちらの方法でも、未コミットのローカル変更はデプロイされません。

作成方法は2つあります。MCP はどちらにも対応していません。

方法	使用するケース	ランタイム
Blueprint（render.yaml）	リポジトリが IaC を使用している場合、またはワークフローをほかの Render サービスと一緒に提供する場合	python、node
render workflows create または Dashboard	Blueprint を使用しないスタンドアロンのワークフロー	python、node、go、ruby、elixir。Docker は Dashboard のみ

Blueprint でデプロイする（推奨）

ワークフローサービスに plan を設定しないでください。タスクのコンピューティングはサービスではなく、コード内のタスクに対する plan で設定します。

services:
  - type: workflow
    name: my-workflow
    runtime: python
    region: oregon
    repo: https://github.com/render-examples/render-workflows-examples-python
    branch: main
    rootDir: hello-world
    buildCommand: pip install -r requirements.txt
    startCommand: python main.py
    envVars:
      - key: RENDER_API_KEY
        sync: false

TypeScript の場合：runtime: node、buildCommand: npm install を設定し、プロジェクトのワークフローエントリーポイントを実行する startCommand を指定します。TypeScript のスターターでは npm start（tsx src/main.ts）を使用します。references/manual-scaffolding.md の手動セットアップでは npm run workflows:start を使用します。両方のコマンドを package.json のスクリプトに合わせてください。プロジェクトに dist/main.js を出力する build スクリプトが定義されている場合に限り、npm run build と node dist/main.js を使用してください。

必須項目：type、name、runtime、region、startCommand に加え、buildCommand と repo。任意項目：branch、rootDir、buildFilter、autoDeployTrigger、envVars（すべてのタスク実行に適用されます）。

スキーマの required 配列に記載されているのは最初の5項目だけです。これを必須項目のすべてだと解釈しないでください。バリデーターは buildCommand または repo が欠けているワークフローも拒否します。

• buildCommand is required for non-docker workflows。ビルドコマンドを省略できるのは Docker ベースのワークフローだけですが、これらは Blueprint に記述できません。そのため、Blueprint のワークフローには必ずビルドコマンドが必要です。
• repo is required for git-based services。origin リモートがあるリポジトリ内から検証している場合にも、このエラーが発生します。これは web などの Git ベースのタイプとは異なる動作です。

注意事項：

• プレビュー環境ではワークフローサービスはスキップされます。ほかの Blueprint リソースは引き続き複製されます。
• Render は、ワークスペース内にある既存の Blueprint 管理対象ワークフローと同じ名前のワークフローを作成する Blueprint を拒否します。
• Workflows intro FAQ には、Blueprint ではワークフローを管理できないとまだ記載されている場合があります。これは古い情報です。変更履歴と https://render.com/schema/render.yaml.json に従ってください。

適用する前に検証してください。

render blueprints validate

検証に合格しても、ランタイムがサポートされている証明にはなりません。現在、スキーマでは runtime: docker がワークフローで拒否されますが、render blueprints validate はこれを受け付けます。

設定には render-blueprints を、適用／ディープリンクのフローには render-deploy を組み合わせてください。

CLI またはダッシュボードで作成する

Blueprint を使わないスタンドアロンのワークフローには、こちらを使用します。対話モードでは設定の入力が求められます。

render workflows create

スターターテンプレートまたはプロジェクトの既存設定にあるビルドコマンドと実行コマンドを使う、非対話モードの場合：

render workflows create \
  --name my-workflow \
  --repo . \
  --branch <branch> \
  --region <region> \
  --runtime python \
  --build-command "pip install -r requirements.txt" \
  --run-command "python main.py"

--repo . を指定すると、リポジトリのリモートが解決されます。サブディレクトリにあるワークフローの場合は、--root-directory を追加します。環境変数は、繰り返し指定できる --env-file フラグと --env-var フラグで渡せます。コマンドや出力にシークレットを決して含めないでください。

ワークフローは Dockerfile からビルドできますが、ダッシュボードの New > Workflow からのみ作成できます。CLI と API では作成できず、Blueprint でも作成できません。Docker ベースのワークフローではビルドコマンドを指定せず、ローカルタスクサーバーに対して実行することもできません。どの作成方法でも、ビルド済みのレジストリイメージを取得することはできません。

後で明示的にリリースする場合は、次を使用します。

render workflows versions release <workflow-id> \
  --commit <pushed-commit-sha> \
  --wait

コマンドが受け付けられたというだけで、デプロイ成功を報告しないでください。リリースを待ってから、想定されるタスクが登録されたこと、および安全なタスクが少なくとも 1 つ、想定される結果とともに終端状態に達したことを確認してください。

render workflows versions list <workflow-id> -o text
render workflows tasks list <ready-workflow-version-id> -o text
render workflows start <workflow-slug>/<task-name> --input='[]' -o json
render workflows tasks runs show <task-run-id> -o json

実行がキュー内または実行中の場合は、上限を定めた期間内で tasks runs show をポーリングします。外部への変更を無期限に再試行するのではなく、リリースまたはタスクのエラーを停止して報告してください。

デプロイに失敗した場合は、references/troubleshooting.md を参照してください。利用可能な場合は、Render のデプロイを幅広く診断するために render-debug スキルを使用してください。

デプロイ済みタスクをトリガーする

タスクスラッグは {workflow-slug}/{task-name} の形式です。

Python、同期処理：

from render import Render

render = Render()
result = render.workflows.run_task("my-workflow/hello", ["world"])
print(result.results)

Python、非同期処理：

from render import RenderAsync

render = RenderAsync()
started = await render.workflows.start_task("my-workflow/hello", ["world"])
finished = await started
print(finished.results)

TypeScript：

import { Render } from "@renderinc/sdk";

const render = new Render();
const started = await render.workflows.startTask("my-workflow/hello", ["world"]);
const finished = await started.get();
console.log(finished.results);

これらのクライアントは、トークンが明示的に渡されない限り RENDER_API_KEY を使用します。認証情報をハードコードするのではなく、環境変数またはシークレットマネージャーを使用してください。

ワークフローには、現在、ネイティブのスケジュール済みトリガーがありません。スケジュール設定が必要な場合は、SDK クライアントまたは API を呼び出す Render cron job を使用してください。

制限、コンピュートプラン、料金

このスキルやそのリファレンスに、コンピュートプラン ID、リソース仕様、クォータ、保持期間、料金をハードコードしないでください。

タスクの plan を設定する前、コストを見積もる前、または容量について助言する前に、references/compute-plans.md と Render Workflows の制限と料金 を参照してください。正しいコードを書くために必要な API 形式上の制約のみをスキルに残してください。

リファレンス

• references/quick-reference.md：SDK 1.x のタスクおよびクライアントの機能
• references/compute-plans.md：タスクの plan 値に関する最新のコンピュートプランのガイダンス
• references/deployments.md：デプロイのライフサイクルとワークフローのタスク登録
• references/service-types.md：ワークフローと他のサービスタイプの選択
• references/task-patterns.md：タスクの連結、ファンアウト、再試行、cron トリガー、ワークフロー間の呼び出し
• references/local-development.md：ローカルサーバー、CLI での実行、環境設定、制限事項
• references/troubleshooting.md：セットアップ、登録、実行、クライアントに関する一般的なエラー
• references/manual-scaffolding.md：workflows init を使わない SDK プロジェクトの直接セットアップ

関連スキル

• render-blueprints：render.yaml の type: workflow、プレビュー、接続設定
• render-deploy：ワークフローを含む複数サービスアプリ向けの Blueprint 適用フロー
• render-debug：デプロイおよび実行時のエラーを診断する
• render-monitor：サービスの健全性とパフォーマンスを確認する

現在のドキュメントの取得

このスキルで最新の Render ドキュメントを参照するよう指示された場合は、次の手順に従ってください。

1. 利用可能な URL 取得ツールまたは curl などの HTTP クライアントを使って、リンク先の Markdown ドキュメントを直接取得します。ウェブ検索の要約でドキュメントを代用しないでください。
2. 取得が成功し、期待したドキュメントが返されたことを確認してから、内容を読みます。ファイルを保存したり、そのパスを表示したりするだけでは不十分です。
3. リクエストに失敗した場合、またはツールで Markdown のレスポンスを読み取れない場合は、リンク先の HTML 版を開いて読みます。
4. どちらの形式も取得できない場合は、最新の参照資料を利用できないことを明示し、スキル内のトピック固有の代替手順に従います。同梱のガイダンスは、変わらない制約に限って使用し、変更される可能性のあるプラットフォームの詳細を推測しないでください。

複数の参照資料が必要な場合は、それぞれにこの手順を適用し、確認できたドキュメントと、取得できなかったドキュメントを区別してください。