kapso-automation

Kapso Automation

使用する場面

Kapso オートメーションを構築して実行するには、このスキルを使用します。対象には、ワークフローの CRUD、グラフの編集、トリガー、実行、関数の管理、D1 データベースの操作が含まれます。

セットアップ

環境変数：

• KAPSO_API_BASE_URL（ホストのみ。/platform/v1 は含めません）
• KAPSO_API_KEY

使用方法

ワークフローグラフを編集する

1. グラフを取得します：node scripts/get-graph.js <workflow_id>（lock_version をメモします）
2. JSON を編集します（以下のグラフのルールを参照）
3. 検証します：node scripts/validate-graph.js --definition-file <path>
4. 更新します：node scripts/update-graph.js <workflow_id> --expected-lock-version <n> --definition-file <path>
5. 再取得して確認します

小規模な編集には、代わりに --old-file と --new-file を指定して edit-graph.js を使用します。

lock_version の競合が発生した場合は、再取得して変更を適用し直し、新しい lock_version で再試行します。

トリガーを管理する

1. 一覧表示します：node scripts/list-triggers.js <workflow_id>
2. 作成します：node scripts/create-trigger.js <workflow_id> --trigger-type <type> --phone-number-id <id>
3. 切り替えます：node scripts/update-trigger.js --trigger-id <id> --active true|false
4. 削除します：node scripts/delete-trigger.js --trigger-id <id>

inbound_message トリガーの場合は、まず node scripts/list-whatsapp-phone-numbers.js を実行して phone_number_id を取得します。

実行をデバッグする

1. 一覧表示します：node scripts/list-executions.js <workflow_id>
2. 詳細を確認します：node scripts/get-execution.js <execution-id>
3. 値を取得します：node scripts/get-context-value.js <execution-id> --variable-path vars.foo
4. イベントを確認します：node scripts/list-execution-events.js <execution-id>

関数を作成してデプロイする

1. ハンドラーのシグネチャに従ってコードを記述します（以下の関数のルールを参照）
2. 作成します：node scripts/create-function.js --name <name> --code-file <path>
3. デプロイします：node scripts/deploy-function.js --function-id <id>
4. 確認します：node scripts/get-function.js --function-id <id>

アプリ連携を使ってエージェントノードを設定する

1. モデルを確認します：node scripts/list-provider-models.js
2. アカウントを確認します：node scripts/list-accounts.js --app-slug <slug>（pipedream_account_id を使用します）
3. アクションを確認します：node scripts/search-actions.js --query <word> --app-slug <slug>（action_id = key）
4. 連携を作成します：node scripts/create-integration.js --action-id <id> --app-slug <slug> --account-id <id> --configured-props <json>
5. flow_agent_app_integration_tools を使って、エージェントノードにツールを追加します

データベースの CRUD

1. テーブルを一覧表示します：node scripts/list-tables.js
2. クエリを実行します：node scripts/query-rows.js --table <name> --filters <json>
3. 行用スクリプトで作成、更新、削除します

グラフのルール

• id が start の開始ノードをちょうど 1 つにします
• 既存のノード ID は変更しないでください
• 新しいノード ID には {node_type}_{timestamp_ms} を使用します
• decide 以外のノードが持つ next エッジは 0 個または 1 個です
• decide エッジのラベルは conditions[].label と一致させてください
• エッジキーには source／target／label を使用します（from／to ではありません）

スキーマの詳細については、references/graph-contract.md を参照してください。

関数のルール

async function handler(request, env) {
  // Parse input
  const body = await request.json();
  // Use env.KV and env.DB as needed
  return new Response(JSON.stringify({ result: "ok" }));
}

• export、export default、アロー関数は使用しないでください
• Response オブジェクトを返してください

実行コンテキスト

常に次の構造を使用します：

• vars - ユーザー定義変数
• system - システム変数
• context - チャネルデータ
• metadata - リクエストメタデータ

スクリプト

ワークフロー

スクリプト	用途
list-workflows.js	ワークフローを一覧表示します（メタデータのみ）
get-workflow.js	ワークフローのメタデータを取得します
create-workflow.js	ワークフローを作成します
update-workflow-settings.js	ワークフローの設定を更新します

グラフ

スクリプト	用途
get-graph.js	ワークフローグラフと lock_version を取得します
edit-graph.js	文字列置換でグラフにパッチを適用します
update-graph.js	グラフ全体を置き換えます
validate-graph.js	グラフ構造をローカルで検証します

トリガー

スクリプト	目的
list-triggers.js	ワークフローのトリガーを一覧表示
create-trigger.js	トリガーを作成
update-trigger.js	トリガーを有効化／無効化
delete-trigger.js	トリガーを削除
list-whatsapp-phone-numbers.js	トリガー設定用の電話番号を一覧表示

実行

スクリプト	目的
list-executions.js	実行を一覧表示
get-execution.js	実行の詳細を取得
get-context-value.js	実行コンテキストから値を読み取る
update-execution-status.js	実行状態を強制的に変更
resume-execution.js	待機中の実行を再開
list-execution-events.js	実行イベントを一覧表示

関数

スクリプト	目的
list-functions.js	プロジェクト関数を一覧表示
get-function.js	関数の詳細とコードを取得
create-function.js	関数を作成
update-function.js	関数コードを更新
deploy-function.js	関数をランタイムにデプロイ
invoke-function.js	ペイロードを指定して関数を呼び出す
list-function-invocations.js	関数の呼び出しを一覧表示

アプリ連携

スクリプト	目的
list-apps.js	連携アプリを検索
search-actions.js	アクションを検索（action_id = key）
get-action-schema.js	アクションの JSON スキーマを取得
list-accounts.js	接続済みアカウントを一覧表示
create-connect-token.js	OAuth 接続リンクを作成
configure-prop.js	prop の remote_options を解決
reload-props.js	動的 prop を再読み込み
list-integrations.js	保存済みの連携を一覧表示
create-integration.js	連携を作成
update-integration.js	連携を更新
delete-integration.js	連携を削除

データベース

スクリプト	目的
list-tables.js	D1 テーブルを一覧表示
get-table.js	テーブルのスキーマとサンプル行を取得
query-rows.js	フィルターを指定して行をクエリ
create-row.js	行を作成
update-row.js	行を更新
upsert-row.js	行をアップサート
delete-row.js	行を削除

注意事項

• インライン JSON よりもファイルパス（--definition-file、--code-file）を優先してください
• action_id は search-actions の key と同じです
• --account-id には list-accounts の pipedream_account_id を使用します
• 変数の CRUD（variables-set.js、variables-delete.js）はブロックされています。Platform API が対応していません
• Platform API 経由での生 SQL の実行はサポートされていません

参考資料

編集する前にお読みください：

• references/graph-contract.md - グラフのスキーマ、計算フィールドと編集可能フィールド、lock_version
• references/node-types.md - ノードの種類と設定の形状
• references/workflow-overview.md - 実行フローと状態

その他の参考資料：

• references/execution-context.md - コンテキストの構造と変数の置換
• references/triggers.md - トリガーの種類と設定
• references/app-integrations.md - アプリ連携と variable_definitions
• references/functions-reference.md - 関数管理
• references/functions-payloads.md - 関数のペイロード形状
• references/databases-reference.md - データベース操作

アセット

ファイル	説明
workflow-linear.json	最小限の線形ワークフロー
workflow-decision.json	最小限の分岐ワークフロー
workflow-agent-simple.json	最小限のエージェントワークフロー
workflow-customer-support-intake-agent.json	カスタマーサポートの問い合わせ受付
workflow-interactive-buttons-decide-function.json	インタラクティブボタン＋条件分岐（関数）
workflow-interactive-buttons-decide-ai.json	インタラクティブボタン＋条件分岐（AI）
workflow-api-template-wait-agent.json	API トリガー＋テンプレート＋エージェント
function-decide-route-interactive-buttons.json	ボタンのルーティング用関数
agent-app-integration-example.json	アプリ連携機能を備えたエージェントノード

関連スキル

• whatsapp-messaging - WhatsApp メッセージングとテンプレート
• whatsapp-flows - WhatsApp Flows
• kapso-api - プラットフォーム API と顧客