catalyst-workflow-scaffold

Catalyst 上で Dapr ワークフローをスキャフォールドする

目標：このスキルを終える時点で、ワークフローが登録され、Catalyst で一度実行され、そのステータスが読み戻されている状態にします。コンパイルはできても一度も実行されていないコードは、スキャフォールドとは言えません。ここで問題が起きる場合、そのほとんどは最初の実行時に発生します。

1. 言語を検出し、ユーザーに尋ねない

言語はこのスキルのパラメーターであり、別のバリエーションではありません。まずリポジトリを確認してください。

トップレベルに見つかったファイル	言語	ワークフロー SDK
pyproject.toml、requirements.txt、*.py	Python	dapr + dapr-ext-workflow
*.csproj、*.sln、global.json	.NET	Dapr.Workflow
pom.xml、build.gradle	Java	io.dapr:dapr-sdk-workflows
go.mod	Go	github.com/dapr/durabletask-go
package.json、tsconfig.json	TypeScript / JavaScript	@dapr/dapr

ディレクトリが空の場合、またはこれらのうち2つが並んでいて、どちらにもワークフローを置く可能性がある場合に限り、質問してください。推測するとビルドできないプロジェクトができあがります。

2. Diagrid アダプターではなく Dapr SDK を追加する

Dapr ワークフローには、検出した言語用の Dapr SDK が必要です。5つすべてが公開されています。Diagrid の *-ai パッケージはエージェントフレームワークとのブリッジであり、ここでは不要です。エージェントのスキャフォールディング手順で使用するものです。

言語	パッケージ座標	最新の検証済み安定版
Python	dapr、dapr-ext-workflow	1.18.3
.NET	Dapr.Workflow	1.18.5
Java	io.dapr:dapr-sdk-workflows	1.18.1
Go	github.com/dapr/durabletask-go	v0.14.0
TypeScript	@dapr/dapr	3.18.0

注意すべきパッケージ座標が3つあります。いずれも、すでに問題を引き起こしたことがあります。

• Go のワークフロー作成機能は github.com/dapr/go-sdk/workflow にはありません。 このパッケージは go-sdk v1.10.0 から v1.13.0 まで存在し、v1.14.0 で削除されました。そのため古いチュートリアルには今でもインポートするよう記載されており、現在は go get も失敗します。作成には github.com/dapr/durabletask-go/workflow を、Dapr API には github.com/dapr/go-sdk/client をインポートしてください。
• Dapr.Workflow 1.19.0 はプレビュー版のみです。 最新版ではなく、最新の安定版を固定してください。
• ワークフロー用の Diagrid パッケージを作り上げてはいけません。 Diagrid.Agents.Workflow はなく、どのレジストリにも Diagrid のワークフローパッケージはありません。

解決されるところを確認していないパッケージ座標は決して記載しないでください。存在しないパッケージ ID を書くと、ユーザーは実在しない Catalyst の問題を調べることになります。これはスキルがないよりも悪い結果です。

3. default という名前のプロジェクトを使用する

プロジェクトを作成してはいけません。 すべての組織には、マネージド pub/sub、マネージド KV ストア、ワークフローストア、エージェントインフラストラクチャがすでに接続された default という名前のプロジェクトが1つあります。ワークフローの履歴はそのマネージドストアに保存されるため、新しくスキャフォールドしたワークフローが起動しても表示されない場合、最もよくある原因は独自に作成したプロジェクトです。

default は組織の初回調整時に一度だけブートストラップされ、削除された場合は再作成されません。決めつけずに catalyst_list_projects で確認してください。見つからない場合は、どのプロジェクトを使うかを尋ね、プロジェクトを作成してはいけません。現在のプロジェクトはないため、呼び出しごとにプロジェクトを渡してください。

マネージドコンポーネントの名前は固定です。ブローカーは pubsub、KV ストアは kvstore です。マネージドワークフローストアは暗黙的に接続されており、コンポーネント名はありません。エージェントインフラストラクチャはマネージド KV ストアとともに提供されます。

どのプランでも、プロジェクトが保持できるのはマネージド pub/sub が1つ、マネージド KV ストアが1つであり、プランをアップグレードしても上限は増えません。そのため、解決策として提案してはいけません。1つのブローカー上でトピックを使い分けて処理を分散してください。これらはコード内の定数ではなく、組織ごとに適用されるプランの値です。したがって、上限が1だと断言するのではなく、catalyst_get_usage で現在のクォータを確認してください。また、ユーザーに上限を引き上げられると約束してはいけません。これはあなたが回答できる技術的な質問ではなく、商業上の判断事項です。

4. リプレイでワークフローの判断が変わらないように記述する

ワークフローの本体は、リプレイのたびに先頭から再実行されます。2回目に異なる結果を返す処理は、実行を破損させます。本体は履歴だけを入力とする純粋関数にし、副作用はすべてアクティビティに移してください。

ワークフロー本体での危険な処理	リプレイで起こること	代わりに使うもの
システム時刻の読み取り（now、UtcNow、time.Now）	リプレイのたびに新しい値が返される	コンテキストの現在時刻 API と永続タイマー API
random、新しい UUID の生成	記録された履歴と食い違う	入力として渡すか、アクティビティ内で生成する
HTTP、データベース、Dapr の呼び出し	リプレイのたびに再実行される	アクティビティに移す
map や dict の反復処理	リプレイごとに順序が安定しない	キーをソートしてから反復する
環境変数、ファイル、グローバル変数、静的変数	リプレイのたびにホストの状態が変わる	入力として渡す
sleep、スレッド、ゴルーチン、Task.Delay	履歴に記録されない	コンテキストの永続タイマー

アクティビティは少なくとも1回実行されます。1つの論理ステップに対してアクティビティが2回実行されることがあります。それぞれが冪等になるようにし、インスタンス ID と安定したステップ名をキーとして使用してください。また、同じワークフロー内の2つのアクティビティが同じ書き込みを担当しないようにしてください。

実行中のインスタンスがある状態でワークフロー内のアクティビティの名前を変更、並べ替え、削除すると、新しいコードに対して古い履歴がリプレイされ、実行が失敗します。代わりに新しいワークフロー名を追加し、古いインスタンスが処理を終えるまで待ってください。ワークフローのバージョン管理は自動では解決されません。

5. Catalyst に対して実行する

1. アプリが存在することを確認します。 プロジェクトとアプリ名を指定して catalyst_get_app を実行します。存在しない場合は App に対して catalyst_apply を実行します（最初に catalyst_get_resource_schema を読み、dry_run で実行してユーザーに表示してから適用します）。書き込みロールが必要です。ツール一覧に catalyst_apply がない場合は、その旨を伝えて停止してください。
2. ワーカーを実行します。 接続値を catalyst_get_connection から取得し、環境変数として設定してプロセスを起動する方法は、catalyst-develop のセクション3に記載されています。手順を独自に考えず、そこに従ってください。

純粋なワークフローワーカーにアプリのポートは必要ありません。 Catalyst に対して送信接続を確立し、作業項目をポーリングするため、公開する受信エンドポイントはなく、リッスンする必要もありません。エンドポイントを登録しないアプリが、ワーカーとして正しい構成です。それでもエンドポイントを設定すると（ヘルスチェックを有効にしたアプリのエンドポイントや、トンネルの --app-port など）、Catalyst はそのエンドポイントでアプリのヘルスチェックを行いますが、何も見つからないため、ワークフローを開始しません。すべての開始が failed to create workflow instance: context canceled で失敗します。

必要のないポートを使うために HTTP サーバーを作らないでください。これは初回実行時によく起こる失敗で、原因がわかりにくいものです。ワーカーはワークフローとすべてのアクティビティを正常に登録したあと、ポートを別のプロセスがすでに使用しているため、バインド時に停止します。そのためログには、正常な起動のあとにワークフローとは無関係なエラーが表示されます。Catalyst から呼び出しがある場合に限り、アプリにエンドポイントを設定してください。たとえば、サービス呼び出し、pub/sub の配信、エージェントのエンドポイントなどです。

アプリ、エージェント、MCP サーバーはそれぞれ ID（API によっては「App ID」）に紐づいています。ツールが appId を要求または返す場合、それはその ID の名前を指します。リソースの status.appIds から読み取ってください（get ツールに含まれます）。独自のコードから登録したエージェントの場合は、レジストリレコードの appId です。

ID の上限を考慮してください。アプリ、エージェント、MCP サーバーはそれぞれ、リージョンごとの上限に対して1つの ID として数えられます。catalyst_get_usage で確認してください。ワークフロー用にアプリを1つ作成し、ユーザーから依頼があった場合にのみ追加してください。ワークフロー自体はクォータの対象ではなく、インスタンスは無料ですが、アプリは無料ではありません。

6. 成功を宣言する前に結果を読み返す

インスタンスを1つ起動して、内容を確認します。

• プロジェクト、アプリの ID、ワークフロー名、および必要な場合は入力を指定して catalyst_start_workflow を実行します。実行 ID が割り当てられて返されるので、控えておきます。
• ID が分からなくなった場合は、プロジェクトに対して catalyst_list_workflow_runs を実行します。
• 実行に対して catalyst_get_workflow_run を実行し、実行グラフと、現在のステップまたは失敗したステップを確認します。

catalyst_start_workflow は書き込みツールであり、書き込み権限のないロールでは使用できません。

ワークフローの探索はマネージドワークフローストアでのみ利用できます。これも default を使う理由の1つです。

フィールドが存在しないことは、空であることを意味しません。 ペイロードを非公開にする場合は、空の値を返すのではなく、キーを削除します。デフォルトの metadata データ共有レベルでは、実行から input、output、customStatus がすべて削除されます。レベルを full に引き上げられるのは組織管理者だけであり、ここから変更することはできません。データ共有ヘッダーを偽造してはいけません。また、回答を完成させるために管理者へレベルの引き上げを依頼してはいけません。

ペイロードが実際に存在しない場合は、その旨とレベルを明示します。「この組織のデータ共有レベル（metadata）では output が共有されていません」と伝えてください。「ワークフローから出力がありませんでした」とは決して言わないでください。ユーザーが、正常に動作しているコードのデバッグに向かってしまいます。セクション7のコンソールリンクを渡し、ユーザー自身で確認できるようにしてください。

ツールが要求を拒否した場合も、ワークフローが失敗したわけではありません。拒否されたことを報告してください。

7. 断定するのではなく、リンクを渡す

アプリが存在し、実行が開始されたら、ユーザー自身で確認できるコンソールリンクを渡します。本番サーバーのコンソールは https://catalyst.diagrid.io です。利用できるルートは次のものだけです。

表示対象	ルート
アプリ	/apps/details/<appId>
ワークフロー実行	/workflows/<appId>/<runId>, optionally /<tab>
アプリのメトリクス	/metrics/appids/<appId>

プロジェクト詳細ページもクォータページもありません。 どちらにもリンクしないでください。プロジェクトのルートは管理者向けのものだけです。

プロジェクトはクエリパラメーターとして指定します。次の2つの表記は互換ではありません。

• 名前のような ID（default など）には ?project=<name>
• 数値の uid（prj- プレフィックスの有無を問わない）には ?projectId=<uid>
• 両方が指定されている場合は、projectId が優先されます

数値の uid を ?project= に指定すると、コンソールはその数値をプロジェクト名として検索し、見つからない場合は何も通知せずにユーザーのデフォルトプロジェクトにフォールバックします。エラーは表示されず、異なるデータが表示されます。名前は project に、数値は projectId に指定してください。どちらを持っているか判断できない場合は、パラメーターを省略してください。

信頼できるリンクを作成できない場合は、アプリ ID と実行 ID をプレーンテキストで表示してください。404 になったり、誤ったプロジェクトに移動したりするリンクは、リンクがないよりも悪い結果になります。

ルール

• Catalyst に関する操作には、すべて Catalyst MCP ツールを使用してください。
• プロジェクトを作成してはいけません。 default を使用してください。なくなっている場合は、使用する既存のプロジェクトを確認してください。プロジェクトがないユーザーには、コンソールでプロジェクトを作成するよう案内してください。
• 確認していないパッケージのバージョンを指定してはいけません。 レジストリを確認するか、バージョンを指定せずにパッケージを案内してください。
• このスキルの言語別バリエーションをスキャフォールディングしてはいけません。 1つのスキルで言語を判別してください。ほぼ同一のスキルを5つ用意すると、同じリクエストを取り合い、どれもうまく機能しなくなります。
• ワークフロー本体に副作用を含めてはいけません。 そのためにアクティビティが用意されています。
• catalyst_* ツールのみを使用してください。 対応する機能のツールがない場合は、MCP ではまだ利用できないと伝え、そこで終了してください。
• 非公開フィールドを空の結果として報告してはいけません。
• コンソール URL を推測してはいけません。 上記のルートを使い、プロジェクトを正しいパラメーターに指定してください。信頼できるリンクを作成できない場合は、識別子をプレーンテキストで表示してください。